diff --git a/.nojekyll b/.nojekyll deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/404.html b/404.html index c0511373d89..b8cc853b524 100644 --- a/404.html +++ b/404.html @@ -16,14 +16,14 @@ Page Not Found · React Native - +

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/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 ea26f8e29bb..06fd05f8ec5 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 @@ -16,7 +16,7 @@ React Native: Bringing modern web techniques to mobile · React Native - + @@ -29,7 +29,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/index.html b/blog/2015/09/14/react-native-for-android/index.html index a7cf3335aec..6415c93f341 100644 --- a/blog/2015/09/14/react-native-for-android/index.html +++ b/blog/2015/09/14/react-native-for-android/index.html @@ -16,7 +16,7 @@ React Native for Android: How we built the first cross-platform React Native app · React Native - + @@ -29,7 +29,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/index.html b/blog/2015/11/23/making-react-native-apps-accessible/index.html index 28e0c37145a..e4b42aa4713 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 @@ -16,7 +16,7 @@ Making React Native apps accessible · React Native - + @@ -29,7 +29,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/index.html b/blog/2016/03/24/introducing-hot-reloading/index.html index 7fa0a96b2a5..4d0e5d4c69d 100644 --- a/blog/2016/03/24/introducing-hot-reloading/index.html +++ b/blog/2016/03/24/introducing-hot-reloading/index.html @@ -16,7 +16,7 @@ Introducing Hot Reloading · React Native - + @@ -39,7 +39,7 @@
if (module.hot) {
module.hot.accept(() => {
const nextRootReducer = require('../reducers/index').default;
store.replaceReducer(nextRootReducer);
});
}
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/index.html b/blog/2016/03/28/dive-into-react-native-performance/index.html index 13fce09faa6..385735734dc 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 @@ -16,7 +16,7 @@ Dive into React Native Performance · React Native - + @@ -29,7 +29,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/index.html b/blog/2016/04/13/react-native-a-year-in-review/index.html index 6223a6c3e71..cb290af3fec 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 @@ -16,7 +16,7 @@ React Native: A year in review · React Native - + @@ -29,7 +29,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/index.html b/blog/2016/07/06/toward-better-documentation/index.html index 728109caea2..e3e56e2a759 100644 --- a/blog/2016/07/06/toward-better-documentation/index.html +++ b/blog/2016/07/06/toward-better-documentation/index.html @@ -16,7 +16,7 @@ Toward Better Documentation · React Native - + @@ -31,7 +31,7 @@
class ScratchPad extends Component {
render() {
return (
<View style={{flex: 1}}>
<Text style={{fontSize: 30, flex: 1, textAlign: 'center'}}>
Isn't this cool?
</Text>
<Text style={{fontSize: 100, flex: 1, textAlign: 'center'}}>
👍
</Text>
</View>
);
}
}
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/index.html b/blog/2016/08/12/react-native-meetup-san-francisco/index.html index 1ab830b785a..ffbb5cd408e 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 @@ -16,7 +16,7 @@ San Francisco Meetup Recap · React Native - + @@ -29,7 +29,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/index.html b/blog/2016/08/19/right-to-left-support-for-react-native-apps/index.html index fc8988f0d6e..3a693820499 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 @@ -16,7 +16,7 @@ Right-to-Left Layout Support For React Native Apps · React Native - + @@ -30,7 +30,7 @@

All Blog Posts

Right-to-Left Layout Support For React Native Apps

Mengjue (Mandy) Wang

Mengjue (Mandy) Wang

Software Engineer Intern at Facebook

After launching an app to the app stores, internationalization is the next step to further your audience reach. Over 20 countries and numerous people around the world use Right-to-Left (RTL) languages. Thus, making your app support RTL for them is necessary.

We're glad to announce that React Native has been improved to support RTL layouts. This is now available in the react-native master branch today, and will be available in the next RC: v0.33.0-rc.

This involved changing css-layout, the core layout engine used by RN, and RN core implementation, as well as specific OSS JS components to support RTL.

To battle test the RTL support in production, the latest version of the Facebook Ads Manager app (the first cross-platform 100% RN app) is now available in Arabic and Hebrew with RTL layouts for both iOS and Android. Here is how it looks like in those RTL languages:

Overview Changes in RN for RTL support

css-layout already has a concept of start and end for the layout. In the Left-to-Right (LTR) layout, start means left, and end means right. But in RTL, start means right, and end means left. This means we can make RN depend on the start and end calculation to compute the correct layout, which includes position, padding, and margin.

In addition, css-layout already makes each component's direction inherits from its parent. This means, we simply need to set the direction of the root component to RTL, and the entire app will flip.

The diagram below describes the changes at high level:

These include:

With this update, when you allow RTL layout for your app:

  • every component layout will flip horizontally
  • some gestures and animations will automatically have RTL layout, if you are using RTL-ready OSS components
  • minimal additional effort may be needed to make your app fully RTL-ready

Making an App RTL-ready

  1. To support RTL, you should first add the RTL language bundles to your app.

  2. Allow RTL layout for your app by calling the allowRTL() function at the beginning of native code. We provided this utility to only apply to an RTL layout when your app is ready. Here is an example:

    iOS:

    // in AppDelegate.m
    [[RCTI18nUtil sharedInstance] allowRTL:YES];

    Android:

    // in MainActivity.java
    I18nUtil sharedI18nUtilInstance = I18nUtil.getInstance();
    sharedI18nUtilInstance.allowRTL(context, true);

  3. For Android, you need add android:supportsRtl="true" to the <application> element in AndroidManifest.xml file.

Now, when you recompile your app and change the device language to an RTL language (e.g. Arabic or Hebrew), your app layout should change to RTL automatically.

Writing RTL-ready Components

In general, most components are already RTL-ready, for example:

  • Left-to-Right Layout
  • Right-to-Left Layout

However, there are several cases to be aware of, for which you will need the I18nManager. In I18nManager, there is a constant isRTL to tell if layout of app is RTL or not, so that you can make the necessary changes according to the layout.

Icons with Directional Meaning

If your component has icons or images, they will be displayed the same way in LTR and RTL layout, because RN will not flip your source image. Therefore, you should flip them according to the layout style.

  • Left-to-Right Layout
  • Right-to-Left Layout

Here are two ways to flip the icon according to the direction:

  • Adding a transform style to the image component:

    <Image
    source={...}
    style={{transform: [{scaleX: I18nManager.isRTL ? -1 : 1}]}}
    />

  • Or, changing the image source according to the direction:

    let imageSource = require('./back.png');
    if (I18nManager.isRTL) {
    imageSource = require('./forward.png');
    }
    return <Image source={imageSource} />;

Gestures and Animations

In Android and iOS development, when you change to RTL layout, the gestures and animations are the opposite of LTR layout. Currently, in RN, gestures and animations are not supported on RN core code level, but on components level. The good news is, some of these components already support RTL today, such as SwipeableRow and NavigationExperimental. However, other components with gestures will need to support RTL manually.

A good example to illustrate gesture RTL support is SwipeableRow.

Gestures Example
// SwipeableRow.js
_isSwipingExcessivelyRightFromClosedPosition(gestureState: Object): boolean {
// ...
const gestureStateDx = IS_RTL ? -gestureState.dx : gestureState.dx;
return (
this._isSwipingRightFromClosed(gestureState) &&
gestureStateDx > RIGHT_SWIPE_THRESHOLD
);
},
Animation Example
// SwipeableRow.js
_animateBounceBack(duration: number): void {
// ...
const swipeBounceBackDistance = IS_RTL ?
-RIGHT_SWIPE_BOUNCE_BACK_DISTANCE :
RIGHT_SWIPE_BOUNCE_BACK_DISTANCE;
this._animateTo(
-swipeBounceBackDistance,
duration,
this._animateToClosedPositionDuringBounce,
);
},

Maintaining Your RTL-ready App

Even after the initial RTL-compatible app release, you will likely need to iterate on new features. To improve development efficiency, I18nManager provides the forceRTL() function for faster RTL testing without changing the test device language. You might want to provide a simple switch for this in your app. Here's an example from the RTL example in the RNTester:

<RNTesterBlock title={'Quickly Test RTL Layout'}>
<View style={styles.flexDirectionRow}>
<Text style={styles.switchRowTextView}>forceRTL</Text>
<View style={styles.switchRowSwitchView}>
<Switch
onValueChange={this._onDirectionChange}
style={styles.rightAlignStyle}
value={this.state.isRTL}
/>
</View>
</View>
</RNTesterBlock>;
_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:

  • Text alignment behaviors differ in Android and iOS
    • In iOS, the default text alignment depends on the active language bundle, they are consistently on one side. In Android, the default text alignment depends on the language of the text content, i.e. English will be left-aligned and Arabic will be right-aligned.
    • In theory, this should be made consistent across platform, but some people may prefer one behavior to another when using an app. More user experience research may be needed to find out the best practice for text alignment.

  • There is no "true" left/right

    As discussed before, we map the left/right styles from the JS side to start/end, all left in code for RTL layout becomes "right" on screen, and right in code becomes "left" on screen. This is convenient because you don't need to change your product code too much, but it means there is no way to specify "true left" or "true right" in the code. In the future, allowing a component to control its direction regardless of the language may be necessary.

  • Make RTL support for gestures and animations more developer friendly

    Currently, there is still some programming effort required to make gestures and animations RTL compatible. In the future, it would be ideal to find a way to make gestures and animations RTL support more developer friendly.

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/index.html b/blog/2016/09/08/exponent-talks-unraveling-navigation/index.html index c9e6e374554..64c094dbbbe 100644 --- a/blog/2016/09/08/exponent-talks-unraveling-navigation/index.html +++ b/blog/2016/09/08/exponent-talks-unraveling-navigation/index.html @@ -16,7 +16,7 @@ Expo Talks: Adam on Unraveling Navigation · React Native - + @@ -29,7 +29,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/index.html b/blog/2016/10/25/0.36-headless-js-the-keyboard-api-and-more/index.html index ff378fe19ac..136848eee40 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 @@ -16,7 +16,7 @@ 0.36: Headless JS, the Keyboard API, & more · React Native - + @@ -31,7 +31,7 @@
// Hide that keyboard!
Keyboard.dismiss();

Animated Division

Combining two animated values via addition, multiplication, and modulo are already supported by React Native. With version 0.36, combining two animated values via division is now possible. There are some cases where an animated value needs to invert another animated value for calculation. An example is inverting a scale (2x --> 0.5x):

const a = Animated.Value(1);
const b = Animated.divide(1, a);
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/index.html b/blog/2016/11/08/introducing-button-yarn-and-a-public-roadmap/index.html index 34dfd03e7d1..0e8ea324d51 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 @@ -16,7 +16,7 @@ Introducing Button, Faster Installs with Yarn, and a Public Roadmap · React Native - + @@ -29,7 +29,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/index.html b/blog/2016/12/05/easier-upgrades/index.html index b86fe4456a9..19b454f86bb 100644 --- a/blog/2016/12/05/easier-upgrades/index.html +++ b/blog/2016/12/05/easier-upgrades/index.html @@ -16,7 +16,7 @@ Easier Upgrades Thanks to Git · React Native - + @@ -30,7 +30,7 @@

All Blog Posts

Easier Upgrades Thanks to Git

Nicolas Cuillery

Nicolas Cuillery

JavaScript consultant and trainer at Zenika

Upgrading to new versions of React Native has been difficult. You might have seen something like this before:

None of those options is ideal. By overwriting the file we lose our local changes. By not overwriting we don't get the latest updates.

Today I am proud to introduce a new tool that helps solve this problem. The tool is called react-native-git-upgrade and uses Git behind the scenes to resolve conflicts automatically whenever possible.

Usage

Requirement: Git has to be available in the PATH. Your project doesn't have to be managed by Git.

Install react-native-git-upgrade globally:

$ npm install -g react-native-git-upgrade

or, using Yarn:

$ yarn global add react-native-git-upgrade

Then, run it inside your project directory:

$ cd MyProject
$ react-native-git-upgrade 0.38.0

Note: Do not run 'npm install' to install a new version of react-native. The tool needs to be able to compare the old and new project template to work correctly. Simply run it inside your app folder as shown above, while still on the old version.

Example output:

You can also run react-native-git-upgrade with no arguments to upgrade to the latest version of React Native.

We try to preserve your changes in Android and iOS build files, so you don't need to run react-native link after an upgrade.

We have designed the implementation to be as little intrusive as possible. It is entirely based on a local Git repository created on-the-fly in a temporary directory. It won't interfere with your project repository (no matter what VCS you use: Git, SVN, Mercurial, ... or none). Your sources are restored in case of unexpected errors.

How does it work?

The key step is generating a Git patch. The patch contains all the changes made in the React Native templates between the version your app is using and the new version.

To obtain this patch, we need to generate an app from the templates embedded in the react-native package inside your node_modules directory (these are the same templates the react-native init commands uses). Then, after the native apps have been generated from the templates in both the current version and the new version, Git is able to produce a patch that is adapted to your project (i.e. containing your app name):

[...]
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/index.html b/blog/2017/01/07/monthly-release-cadence/index.html index f8519cdccd4..b18fba98a26 100644 --- a/blog/2017/01/07/monthly-release-cadence/index.html +++ b/blog/2017/01/07/monthly-release-cadence/index.html @@ -16,7 +16,7 @@ A Monthly Release Cadence: Releasing December and January RC · React Native - + @@ -29,7 +29,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/index.html b/blog/2017/02/14/using-native-driver-for-animated/index.html index 55ba040dfd6..1d852c9df39 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 @@ -16,7 +16,7 @@ Using Native Driver for Animated · React Native - + @@ -29,7 +29,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/index.html b/blog/2017/03/13/better-list-views/index.html index a8c6c7ddba7..471497f4335 100644 --- a/blog/2017/03/13/better-list-views/index.html +++ b/blog/2017/03/13/better-list-views/index.html @@ -16,7 +16,7 @@ Better List Views in React Native · React Native - + @@ -30,7 +30,7 @@

All Blog Posts

Better List Views in React Native

Spencer Ahrens

Spencer Ahrens

Software Engineer at Facebook

Many of you have started playing with some of our new List components already after our teaser announcement in the community group, but we are officially announcing them today! No more ListViews or DataSources, stale rows, ignored bugs, or excessive memory consumption - with the latest React Native March 2017 release candidate (0.43-rc.1) you can pick from the new suite of components what best fits your use-case, with great perf and feature sets out of the box:

<FlatList>

This is the workhorse component for simple, performant lists. Provide an array of data and a renderItem function and you're good to go:

<FlatList
data={[{title: 'Title Text', key: 'item1'}, ...]}
renderItem={({item}) => <ListItem title={item.title} />}
/>

<SectionList>

If you want to render a set of data broken into logical sections, maybe with section headers (e.g. in an alphabetical address book), and potentially with heterogeneous data and rendering (such as a profile view with some buttons followed by a composer, then a photo grid, then a friend grid, and finally a list of stories), this is the way to go.

<SectionList
renderItem={({item}) => <ListItem title={item.title} />}
renderSectionHeader={({section}) => <H1 title={section.key} />}
sections={[ // homogeneous rendering between sections
{data: [...], key: ...},
{data: [...], key: ...},
{data: [...], key: ...},
]}
/>
<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:

  • Scroll loading (onEndReached).
  • Pull to refresh (onRefresh / refreshing).
  • Configurable viewability (VPV) callbacks (onViewableItemsChanged / viewabilityConfig).
  • Horizontal mode (horizontal).
  • Intelligent item and section separators.
  • Multi-column support (numColumns)
  • scrollToEnd, scrollToIndex, and scrollToItem
  • Better Flow typing.

Some Caveats

  • The internal state of item subtrees 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.

  • These components are based on PureComponent which means that they will not re-render if props remains shallow-equal. Make sure that everything your renderItem function depends on directly is passed as a prop that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state. For example:

    <FlatList
    data={this.state.data}
    renderItem={({ item }) => (
    <MyItem
    item={item}
    onPress={() =>
    this.setState((oldState) => ({
    selected: {
    // New instance breaks `===`
    ...oldState.selected, // copy old data
    [item.key]: !oldState.selected[item.key] // toggle
    }
    }))
    }
    selected={
    !!this.state.selected[item.key] // renderItem depends on state
    }
    />
    )}
    selected={
    // Can be any prop that doesn't collide with existing props
    this.state.selected // A change to selected should re-render FlatList
    }
    />

  • 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, these new lists look for a key prop on each item and use that for the React key. Alternatively, you can provide a custom keyExtractor prop.

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

  • Migration of existing surfaces (ultimately deprecation of ListView).
  • More features as we see/hear the need (let us know!).
  • Sticky section header support.
  • More performance optimizations.
  • Support functional item components with state.
- + 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 4690c325c58..9d8351e863b 100644 --- a/blog/2017/03/13/idx-the-existential-function/index.html +++ b/blog/2017/03/13/idx-the-existential-function/index.html @@ -16,7 +16,7 @@ idx: The Existential Function · React Native - + @@ -29,7 +29,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/index.html b/blog/2017/03/13/introducing-create-react-native-app/index.html index e81d4d5072f..bad75ba4755 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 @@ -16,7 +16,7 @@ Introducing Create React Native App · React Native - + @@ -29,7 +29,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/index.html b/blog/2017/06/21/react-native-monthly-1/index.html index 583515ec105..fc71dca3401 100644 --- a/blog/2017/06/21/react-native-monthly-1/index.html +++ b/blog/2017/06/21/react-native-monthly-1/index.html @@ -16,7 +16,7 @@ React Native Monthly #1 · React Native - + @@ -29,7 +29,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/index.html b/blog/2017/07/28/react-native-monthly-2/index.html index 0a3eaa77a01..5595c6070d0 100644 --- a/blog/2017/07/28/react-native-monthly-2/index.html +++ b/blog/2017/07/28/react-native-monthly-2/index.html @@ -16,7 +16,7 @@ React Native Monthly #2 · React Native - + @@ -29,7 +29,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/index.html b/blog/2017/08/07/react-native-performance-in-marketplace/index.html index e2ab8d14c00..cc9d9abd9a8 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 @@ -16,7 +16,7 @@ React Native Performance in Marketplace · React Native - + @@ -29,7 +29,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/index.html b/blog/2017/08/30/react-native-monthly-3/index.html index 383381f57a9..d33a40630c8 100644 --- a/blog/2017/08/30/react-native-monthly-3/index.html +++ b/blog/2017/08/30/react-native-monthly-3/index.html @@ -16,7 +16,7 @@ React Native Monthly #3 · React Native - + @@ -29,7 +29,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/index.html b/blog/2017/09/21/react-native-monthly-4/index.html index efd694cc4e0..8a3da5b9743 100644 --- a/blog/2017/09/21/react-native-monthly-4/index.html +++ b/blog/2017/09/21/react-native-monthly-4/index.html @@ -16,7 +16,7 @@ React Native Monthly #4 · React Native - + @@ -29,7 +29,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/index.html b/blog/2017/11/06/react-native-monthly-5/index.html index 564c0b36b69..a78526bbacc 100644 --- a/blog/2017/11/06/react-native-monthly-5/index.html +++ b/blog/2017/11/06/react-native-monthly-5/index.html @@ -16,7 +16,7 @@ React Native Monthly #5 · React Native - + @@ -29,7 +29,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/index.html b/blog/2018/01/09/react-native-monthly-6/index.html index 931e05d24f5..529499a0291 100644 --- a/blog/2018/01/09/react-native-monthly-6/index.html +++ b/blog/2018/01/09/react-native-monthly-6/index.html @@ -16,7 +16,7 @@ React Native Monthly #6 · React Native - + @@ -29,7 +29,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/index.html b/blog/2018/01/18/implementing-twitters-app-loading-animation-in-react-native/index.html index 35da6d0df1b..b64c1a4e067 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 @@ -16,7 +16,7 @@ Implementing Twitter’s App Loading Animation in React Native · React Native - + @@ -34,7 +34,7 @@
const appScale = {
transform: [
{
scale: loadingProgress.interpolate({
inputRange: [0, 100],
outputRange: [1.1, 1]
})
}
]
};

Now that we have these style objects, we can use them when rendering the snippet of the view from earlier in the post. Note that only Animated.View, Animated.Text, and Animated.Image are able to use style objects that use Animated.Value.

const fullScreenBlueLayer = (
<View style={styles.fullScreenBlueLayer} />
);
const fullScreenWhiteLayer = (
<View style={styles.fullScreenWhiteLayer} />
);
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/index.html b/blog/2018/03/05/AWS-app-sync/index.html index 1b35ac7e620..69e084d3322 100644 --- a/blog/2018/03/05/AWS-app-sync/index.html +++ b/blog/2018/03/05/AWS-app-sync/index.html @@ -16,7 +16,7 @@ Using AWS with React Native · React Native - + @@ -35,7 +35,7 @@
export default withAuthenticator(App);

The underlying component is also provided as <Authenticator />, which gives you full control to customize the UI. It also gives you some properties around managing the state of the user, such as if they've signed in or are waiting for MFA confirmation, and callbacks that you can fire when state changes.

Similarly, you'll find general React components that you can use for different use cases. You can customize these to your needs, for example, to show all private images from Amazon S3 in the Storage module:

<S3Album
level="private"
path={path}
filter={(item) => /jpg/i.test(item.path)}/>

You can control many of the component features via props, as shown earlier, with public or private storage options. There are even capabilities to automatically gather analytics when users interact with certain UI components:

return <S3Album track/>

AWS Amplify favors a convention over configuration style of development, with a global initialization routine or initialization at the category level. The quickest way to get started is with an aws-exports file. However, developers can also use the library independently with existing resources.

For a deep dive into the philosophy and to see a full demo, check out the video from AWS re:Invent.

AWS AppSync

Shortly after the launch of AWS Amplify, we also released AWS AppSync. This is a fully managed GraphQL service that has both offline and real-time capabilities. Although you can use GraphQL in different client programming languages (including native Android and iOS), it's quite popular among React Native developers. This is because the data model fits nicely into a unidirectional data flow and component hierarchy.

AWS AppSync enables you to connect to resources in your own AWS account, meaning you own and control your data. This is done by using data sources, and the service supports Amazon DynamoDB, Amazon Elasticsearch, and AWS Lambda. This enables you to combine functionality (such as NoSQL and full-text search) in a single GraphQL API as a schema. This enables you to mix and match data sources. The AppSync service can also provision from a schema, so if you aren't familiar with AWS services, you can write GraphQL SDL, click a button, and you're automatically up and running.

The real-time functionality in AWS AppSync is controlled via GraphQL subscriptions with a well-known, event-based pattern. Because subscriptions in AWS AppSync are controlled on the schema with a GraphQL directive, and a schema can use any data source, this means you can trigger notifications from database operations with Amazon DynamoDB and Amazon Elasticsearch Service, or from other parts of your infrastructure with AWS Lambda.

In a way similar to AWS Amplify, you can use enterprise security features on your GraphQL API with AWS AppSync. The service lets you get started quickly with API keys. However, as you roll to production it can transition to using AWS Identity and Access Management (IAM) or OIDC tokens from Amazon Cognito user pools. You can control access at the resolver level with policies on types. You can even use logical checks for fine-grained access control checks at run time, such as detecting if a user is the owner of a specific database resource. There are also capabilities around checking group membership for executing resolvers or individual database record access.

To help React Native developers learn more about these technologies, there is a built-in GraphQL sample schema that you can launch on the AWS AppSync console homepage. This sample deploys a GraphQL schema, provisions database tables, and connects queries, mutations, and subscriptions automatically for you. There is also a functioning React Native example for AWS AppSync which leverages this built in schema (as well as a React example), which enable you to get both your client and cloud components running in minutes.

Getting started is simple when you use the AWSAppSyncClient, which plugs in to the Apollo Client. The AWSAppSyncClient handles security and signing for your GraphQL API, offline functionality, and the subscription handshake and negotiation process:

import AWSAppSyncClient from "aws-appsync";
import { Rehydrated } from 'aws-appsync-react';
import { AUTH_TYPE } from "aws-appsync/lib/link/auth-link";
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/index.html b/blog/2018/03/22/building-input-accessory-view-for-react-native/index.html index 6ec8d7a8e54..483b591f93a 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 @@ -16,7 +16,7 @@ Building <InputAccessoryView> For React Native · React Native - + @@ -30,7 +30,7 @@

All Blog Posts

Building <InputAccessoryView> For React Native

Peter Argany

Peter Argany

Software Engineer at Facebook

Motivation

Three years ago, a GitHub issue was opened to support input accessory view from React Native.

In the ensuing years, there have been countless '+1s', various workarounds, and zero concrete changes to RN on this issue - until today. Starting with iOS, we're exposing an API for accessing the native input accessory view and we are excited to share how we built it.

Background

What exactly is an input accessory view? Reading Apple's developer documentation, we learn that it's a custom view which can be anchored to the top of the system keyboard whenever a receiver becomes the first responder. Anything that inherits from UIResponder can redeclare the .inputAccessoryView property as read-write, and manage a custom view here. The responder infrastructure mounts the view, and keeps it in sync with the system keyboard. Gestures which dismiss the keyboard, like a drag or tap, are applied to the input accessory view at the framework level. This allows us to build content with interactive keyboard dismissal, an integral feature in top-tier messaging apps like iMessage and WhatsApp.

There are two common use cases for anchoring a view to the top of the keyboard. The first is creating a keyboard toolbar, like the Facebook composer background picker.

In this scenario, the keyboard is focused on a text input field, and the input accessory view is used to provide additional keyboard functionality. This functionality is contextual to the type of input field. In a mapping application it could be address suggestions, or in a text editor, it could be rich text formatting tools.

The Objective-C UIResponder who owns the <InputAccessoryView> in this scenario should be clear. The <TextInput> has become first responder, and under the hood this becomes an instance of UITextView or UITextField.

The second common scenario is sticky text inputs:

Here, the text input is actually part of the input accessory view itself. This is commonly used in messaging applications, where a message can be composed while scrolling through a thread of previous messages.

Who owns the <InputAccessoryView> in this example? Can it be the UITextView or UITextField again? The text input is inside the input accessory view, this sounds like a circular dependency. Solving this issue alone is another blog post in itself. Spoilers: the owner is a generic UIView subclass who we manually tell to becomeFirstResponder.

API Design

We now know what an <InputAccessoryView> is, and how we want to use it. The next step is designing an API that makes sense for both use cases, and works well with existing React Native components like <TextInput>.

For keyboard toolbars, there are a few things we want to consider:

  1. We want to be able to hoist any generic React Native view hierarchy into the <InputAccessoryView>.
  2. We want this generic and detached view hierarchy to accept touches and be able to manipulate application state.
  3. We want to link an <InputAccessoryView> to a particular <TextInput>.
  4. We want to be able to share an <InputAccessoryView> across multiple text inputs, without duplicating any code.

We can achieve #1 using a concept similar to React portals. In this design, we portal React Native views to a UIView hierarchy managed by the responder infrastructure. Since React Native views render as UIViews, this is actually quite straightforward - we can just override:

- (void)insertReactSubview:(UIView *)subview atIndex:(NSInteger)atIndex

and pipe all the subviews to a new UIView hierarchy. For #2, we set up a new RCTTouchHandler for the <InputAccessoryView>. State updates are achieved by using regular event callbacks. For #3 and #4, we use the nativeID field to locate the accessory view UIView hierarchy in native code during the creation of a <TextInput> component. This function uses the .inputAccessoryView property of the underlying native text input. Doing this effectively links <InputAccessoryView> to <TextInput> in their ObjC implementations.

Supporting sticky text inputs (scenario 2) adds a few more constraints. For this design, the input accessory view has a text input as a child, so linking via nativeID is not an option. Instead, we set the .inputAccessoryView of a generic off-screen UIView to our native <InputAccessoryView> hierarchy. By manually telling this generic UIView to become first responder, the hierarchy is mounted by responder infrastructure. This concept is explained thoroughly in the aforementioned blog post.

Pitfalls

Of course not everything was smooth sailing while building this API. Here are a few pitfalls we encountered, along with how we fixed them.

An initial idea for building this API involved listening to NSNotificationCenter for UIKeyboardWill(Show/Hide/ChangeFrame) events. This pattern is used in some open-sourced libraries, and internally in some parts of the Facebook app. Unfortunately, UIKeyboardDidChangeFrame events were not being called in time to update the <InputAccessoryView> frame on swipes. Also, changes in keyboard height are not captured by these events. This creates a class of bugs that manifest like this:

On iPhone X, text and emoji keyboard are different heights. Most applications using keyboard events to manipulate text input frames had to fix the above bug. Our solution was to commit to using the .inputAccessoryView property, which meant that the responder infrastructure handles frame updates like this.

Another tricky bug we encountered was avoiding the home pill on iPhone X. You may be thinking, “Apple developed safeAreaLayoutGuide for this very reason, this is trivial!”. We were just as naive. The first issue is that the native <InputAccessoryView> implementation has no window to anchor to until the moment it is about to appear. That's alright, we can override -(BOOL)becomeFirstResponder and enforce layout constraints there. Adhering to these constraints bumps the accessory view up, but another bug arises:

The input accessory view successfully avoids the home pill, but now content behind the unsafe area is visible. The solution lies in this radar. I wrapped the native <InputAccessoryView> hierarchy in a container which doesn't conform to the safeAreaLayoutGuide constraints. The native container covers the content in the unsafe area, while the <InputAccessoryView> stays within the safe area boundaries.

Example Usage

Here's an example which builds a keyboard toolbar button to reset <TextInput> state.

class TextInputAccessoryViewExample extends React.Component<
{},
*
> {
constructor(props) {
super(props);
this.state = { text: 'Placeholder Text' };
}
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/index.html b/blog/2018/04/09/build-com-app/index.html index 4789985aeab..580e2cbd65a 100644 --- a/blog/2018/04/09/build-com-app/index.html +++ b/blog/2018/04/09/build-com-app/index.html @@ -16,7 +16,7 @@ Built with React Native - The Build.com app · React Native - + @@ -29,7 +29,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/index.html b/blog/2018/05/07/using-typescript-with-react-native/index.html index 331cba802bc..46d96b4b82f 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 @@ -16,7 +16,7 @@ Using TypeScript with React Native · React Native - + @@ -41,7 +41,7 @@
import { Hello } from '../Hello';
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/index.html b/blog/2018/06/14/state-of-react-native-2018/index.html index 47b66d06fe4..7e1dfeb61e4 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 @@ -16,7 +16,7 @@ State of React Native 2018 · React Native - + @@ -29,7 +29,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/index.html b/blog/2018/07/04/releasing-react-native-056/index.html index 126de8bee8a..cddd646d02f 100644 --- a/blog/2018/07/04/releasing-react-native-056/index.html +++ b/blog/2018/07/04/releasing-react-native-056/index.html @@ -16,7 +16,7 @@ Releasing 0.56 · React Native - + @@ -29,7 +29,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/index.html b/blog/2018/08/13/react-native-accessibility-updates/index.html index ecb6cd2a195..14d036f43f3 100644 --- a/blog/2018/08/13/react-native-accessibility-updates/index.html +++ b/blog/2018/08/13/react-native-accessibility-updates/index.html @@ -16,7 +16,7 @@ Accessibility API Updates · React Native - + @@ -29,7 +29,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/index.html b/blog/2018/08/27/wkwebview/index.html index d71ecd75355..b155506d5ce 100644 --- a/blog/2018/08/27/wkwebview/index.html +++ b/blog/2018/08/27/wkwebview/index.html @@ -16,7 +16,7 @@ Introducing new iOS WebViews · React Native - + @@ -29,7 +29,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/index.html b/blog/2018/11/01/oss-roadmap/index.html index 0fe9c3a3db5..3084ad2703c 100644 --- a/blog/2018/11/01/oss-roadmap/index.html +++ b/blog/2018/11/01/oss-roadmap/index.html @@ -16,7 +16,7 @@ Open Source Roadmap · React Native - + @@ -29,7 +29,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/index.html b/blog/2019/01/07/state-of-react-native-community/index.html index 2d09a8113cf..850dfd5fbf8 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 @@ -16,7 +16,7 @@ The State of the React Native Community in 2018 · React Native - + @@ -29,7 +29,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/index.html b/blog/2019/03/01/react-native-open-source-update/index.html index 4ba15d6d918..d8afbfd78a6 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 @@ -16,7 +16,7 @@ React Native Open Source Update March 2019 · React Native - + @@ -29,7 +29,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/index.html b/blog/2019/03/12/releasing-react-native-059/index.html index b1e3926f531..f3a554ab02b 100644 --- a/blog/2019/03/12/releasing-react-native-059/index.html +++ b/blog/2019/03/12/releasing-react-native-059/index.html @@ -16,7 +16,7 @@ Releasing React Native 0.59 · React Native - + @@ -29,7 +29,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/index.html b/blog/2019/05/01/react-native-at-f8-and-podcast/index.html index b214310e318..3dcc7948f8a 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 @@ -16,7 +16,7 @@ React Native at F8 and Open Source Podcast · React Native - + @@ -29,7 +29,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/index.html b/blog/2019/06/12/react-native-open-source-update/index.html index 7389ad4ba5b..ab6f7b32a21 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 @@ -16,7 +16,7 @@ React Native Open Source Update June 2019 · React Native - + @@ -29,7 +29,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/index.html b/blog/2019/07/03/version-60/index.html index 1f7d1c4b2b4..8f168f4b837 100644 --- a/blog/2019/07/03/version-60/index.html +++ b/blog/2019/07/03/version-60/index.html @@ -16,7 +16,7 @@ Announcing React Native 0.60 · React Native - + @@ -29,7 +29,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/index.html b/blog/2019/07/17/hermes/index.html index be0c038542e..08a6e11aa35 100644 --- a/blog/2019/07/17/hermes/index.html +++ b/blog/2019/07/17/hermes/index.html @@ -16,7 +16,7 @@ Meet Hermes, a new JavaScript Engine optimized for React Native · React Native - + @@ -29,7 +29,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/index.html b/blog/2019/09/18/version-0.61/index.html index 7489c9552e4..19fc115a38f 100644 --- a/blog/2019/09/18/version-0.61/index.html +++ b/blog/2019/09/18/version-0.61/index.html @@ -16,7 +16,7 @@ Announcing React Native 0.61 with Fast Refresh · React Native - + @@ -29,7 +29,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/index.html b/blog/2019/11/18/react-native-doctor/index.html index 812bb7af1ce..7f3e4e5b5ef 100644 --- a/blog/2019/11/18/react-native-doctor/index.html +++ b/blog/2019/11/18/react-native-doctor/index.html @@ -16,7 +16,7 @@ Meet Doctor, a new React Native command · React Native - + @@ -29,7 +29,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/index.html b/blog/2020/03/26/version-0.62/index.html index 0cb19d4d1db..9992154a336 100644 --- a/blog/2020/03/26/version-0.62/index.html +++ b/blog/2020/03/26/version-0.62/index.html @@ -16,7 +16,7 @@ Announcing React Native 0.62 with Flipper · React Native - + @@ -30,7 +30,7 @@

All Blog Posts

Announcing React Native 0.62 with Flipper

Rick Hanlon

Rick Hanlon

React Native Core at Facebook

Today we’re releasing React Native version 0.62 which includes support for Flipper by default.

This release comes in the midst of a global pandemic. We’re releasing this version today to respect the work of hundreds of contributors who made this release possible and to prevent the release from falling too far behind master. Please be mindful of the reduced capacity of contributors to help with issues and prepare to delay upgrading if necessary.

Flipper by default

Flipper is a developer tool for debugging mobile apps. It’s popular in the Android and iOS communities, and in this release we’ve enabled support by default for new and existing React Native apps.

Screenshot of Flipper for React Native

Flipper provides the following features out of the box:

  • Metro Actions: Reload the app and trigger the Dev Menu right from the toolbar.
  • Crash Reporter: View crash reports from Android and iOS devices.
  • React DevTools: Use the newest version of React DevTools right alongside all your other tools.
  • Network Inspector: View all of the network requests made by device applications.
  • Metro and Device Logs: View, search, and filter all logs from both Metro and the Device.
  • Native Layout Inspector: View and edit the native layout output by the React Native renderer.
  • Database and Preference Inspectors: View and edit the device databases and preferences.

Additionally, since Flipper is an extensible platform, it provides a marketplace that pulls plugins from NPM so you can publish and install custom plugins specific to your workflows. See the available plugins here.

For more information, check out the Flipper documentation.

New dark mode features

We’ve added a new Appearance module to provide access to the user's appearance preferences, such as their preferred color scheme (light or dark).

const colorScheme = Appearance.getColorScheme();
if (colorScheme === 'dark') {
// Use dark color scheme
}

We’ve also added a hook to subscribe to state updates to the users preferences:

import { Text, useColorScheme } from 'react-native';
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

  • LogBox: We’re adding the new LogBox error and warning experience as an opt-in; to enable it, add require('react-native').unstable_enableLogBox() to your index.js file.
  • React DevTools v4: This change includes an upgrade to the latest React DevTools which offers significant performance gains, an improved navigation experience, and full support for React Hooks.
  • Accessibility improvements: We’ve made improvements to accessibility including adding accessibilityValue, missing props on Touchables, onSlidingComplete accessibility events, and changing the default role of Switch component from "button" to "switch".

Breaking changes

  • Remove PropTypes: We're removing propTypes from core components in order to reduce the app size impact of React Native core and to favor static type systems which check at compile time instead of runtime.
  • Remove accessibilityStates: We’ve removed the deprecated accessibilityStates property in favor of the new accessibilityState prop which is a more semantically rich way for components to describe information about their state to accessibility services.
  • TextInput changes: We removed onTextInput from TextInput as it’s uncommon, not W3C compliant, and difficult to implement in Fabric. We also removed the undocumented inputView prop, and selectionState.

Deprecations

  • AccessibilityInfo.fetch was already deprecated, but in this release we added a warning.
  • Setting useNativeDriver is now required to support switching the default in the future.
  • The ref of an Animated component is now the internal component and deprecated getNode.

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/index.html b/blog/2020/07/06/version-0.63/index.html index 687756de04f..1da9a31df18 100644 --- a/blog/2020/07/06/version-0.63/index.html +++ b/blog/2020/07/06/version-0.63/index.html @@ -16,7 +16,7 @@ Announcing React Native 0.63 with LogBox · React Native - + @@ -34,7 +34,7 @@
const customDynamicTextColor = DynamicColorIOS({
dark: 'lightskyblue',
light: 'midnightblue'
});
<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/index.html b/blog/2020/07/17/react-native-principles/index.html index ed353729252..c250791f25e 100644 --- a/blog/2020/07/17/react-native-principles/index.html +++ b/blog/2020/07/17/react-native-principles/index.html @@ -16,7 +16,7 @@ React Native Team Principles · React Native - + @@ -29,7 +29,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/index.html b/blog/2020/07/23/docs-update/index.html index e706c56ef21..f77daa9b3d5 100644 --- a/blog/2020/07/23/docs-update/index.html +++ b/blog/2020/07/23/docs-update/index.html @@ -16,7 +16,7 @@ React Native Documentation Update · React Native - + @@ -29,7 +29,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/index.html b/blog/index.html index 9854cb437da..1dc09f2b041 100644 --- a/blog/index.html +++ b/blog/index.html @@ -16,7 +16,7 @@ Blog · React Native - + @@ -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.

Announcing React Native 0.62 with Flipper

Rick Hanlon

Rick Hanlon

React Native Core at Facebook

Today we’re releasing React Native version 0.62 which includes support for Flipper by default.

This release comes in the midst of a global pandemic. We’re releasing this version today to respect the work of hundreds of contributors who made this release possible and to prevent the release from falling too far behind master. Please be mindful of the reduced capacity of contributors to help with issues and prepare to delay upgrading if necessary.

Flipper by default

Flipper is a developer tool for debugging mobile apps. It’s popular in the Android and iOS communities, and in this release we’ve enabled support by default for new and existing React Native apps.

Screenshot of Flipper for React Native

Flipper provides the following features out of the box:

Additionally, since Flipper is an extensible platform, it provides a marketplace that pulls plugins from NPM so you can publish and install custom plugins specific to your workflows. See the available plugins here.

For more information, check out the Flipper documentation.

New dark mode features

We’ve added a new Appearance module to provide access to the user's appearance preferences, such as their preferred color scheme (light or dark).

const colorScheme = Appearance.getColorScheme();
if (colorScheme === 'dark') {
// Use dark color scheme
}

We’ve also added a hook to subscribe to state updates to the users preferences:

import { Text, useColorScheme } from 'react-native';
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/page/2/index.html b/blog/page/2/index.html index 10db9892135..23b22cc9319 100644 --- a/blog/page/2/index.html +++ b/blog/page/2/index.html @@ -16,7 +16,7 @@ Blog · React Native - + @@ -51,7 +51,7 @@
import { Hello } from '../Hello';
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.

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:

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:

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:

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/index.html b/blog/page/3/index.html index 2d11bcef843..b83fd958da3 100644 --- a/blog/page/3/index.html +++ b/blog/page/3/index.html @@ -16,7 +16,7 @@ Blog · React Native - + @@ -51,7 +51,7 @@
const appScale = {
transform: [
{
scale: loadingProgress.interpolate({
inputRange: [0, 100],
outputRange: [1.1, 1]
})
}
]
};

Now that we have these style objects, we can use them when rendering the snippet of the view from earlier in the post. Note that only Animated.View, Animated.Text, and Animated.Image are able to use style objects that use Animated.Value.

const fullScreenBlueLayer = (
<View style={styles.fullScreenBlueLayer} />
);
const fullScreenWhiteLayer = (
<View style={styles.fullScreenWhiteLayer} />
);
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

Infinite Red

Microsoft

Wix

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

Expo

Facebook

Infinite Red

Shoutem

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

GeekyAnts

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

Expo

Facebook

Microsoft

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

Expo

Facebook

Microsoft

Shoutem

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

Expo

Facebook

GeekyAnts

Infinite Red

Microsoft

Shoutem

Wix

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

Callstack

Expo

Facebook

GeekyAnts

Microsoft

Shoutem

Wix

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/index.html b/blog/page/4/index.html index 47d4849a96b..a972d44d14d 100644 --- a/blog/page/4/index.html +++ b/blog/page/4/index.html @@ -16,7 +16,7 @@ Blog · React Native - + @@ -44,7 +44,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

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.

Right-to-Left Layout Support For React Native Apps

Mengjue (Mandy) Wang

Mengjue (Mandy) Wang

Software Engineer Intern at Facebook

After launching an app to the app stores, internationalization is the next step to further your audience reach. Over 20 countries and numerous people around the world use Right-to-Left (RTL) languages. Thus, making your app support RTL for them is necessary.

We're glad to announce that React Native has been improved to support RTL layouts. This is now available in the react-native master branch today, and will be available in the next RC: v0.33.0-rc.

This involved changing css-layout, the core layout engine used by RN, and RN core implementation, as well as specific OSS JS components to support RTL.

To battle test the RTL support in production, the latest version of the Facebook Ads Manager app (the first cross-platform 100% RN app) is now available in Arabic and Hebrew with RTL layouts for both iOS and Android. Here is how it looks like in those RTL languages:

Overview Changes in RN for RTL support

css-layout already has a concept of start and end for the layout. In the Left-to-Right (LTR) layout, start means left, and end means right. But in RTL, start means right, and end means left. This means we can make RN depend on the start and end calculation to compute the correct layout, which includes position, padding, and margin.

In addition, css-layout already makes each component's direction inherits from its parent. This means, we simply need to set the direction of the root component to RTL, and the entire app will flip.

The diagram below describes the changes at high level:

These include:

With this update, when you allow RTL layout for your app:

Making an App RTL-ready

  1. To support RTL, you should first add the RTL language bundles to your app.

  2. Allow RTL layout for your app by calling the allowRTL() function at the beginning of native code. We provided this utility to only apply to an RTL layout when your app is ready. Here is an example:

    iOS:

    // in AppDelegate.m
    [[RCTI18nUtil sharedInstance] allowRTL:YES];

    Android:

    // in MainActivity.java
    I18nUtil sharedI18nUtilInstance = I18nUtil.getInstance();
    sharedI18nUtilInstance.allowRTL(context, true);

  3. For Android, you need add android:supportsRtl="true" to the <application> element in AndroidManifest.xml file.

Now, when you recompile your app and change the device language to an RTL language (e.g. Arabic or Hebrew), your app layout should change to RTL automatically.

Writing RTL-ready Components

In general, most components are already RTL-ready, for example:

However, there are several cases to be aware of, for which you will need the I18nManager. In I18nManager, there is a constant isRTL to tell if layout of app is RTL or not, so that you can make the necessary changes according to the layout.

Icons with Directional Meaning

If your component has icons or images, they will be displayed the same way in LTR and RTL layout, because RN will not flip your source image. Therefore, you should flip them according to the layout style.

Here are two ways to flip the icon according to the direction:

Gestures and Animations

In Android and iOS development, when you change to RTL layout, the gestures and animations are the opposite of LTR layout. Currently, in RN, gestures and animations are not supported on RN core code level, but on components level. The good news is, some of these components already support RTL today, such as SwipeableRow and NavigationExperimental. However, other components with gestures will need to support RTL manually.

A good example to illustrate gesture RTL support is SwipeableRow.

Gestures Example
// SwipeableRow.js
_isSwipingExcessivelyRightFromClosedPosition(gestureState: Object): boolean {
// ...
const gestureStateDx = IS_RTL ? -gestureState.dx : gestureState.dx;
return (
this._isSwipingRightFromClosed(gestureState) &&
gestureStateDx > RIGHT_SWIPE_THRESHOLD
);
},
Animation Example
// SwipeableRow.js
_animateBounceBack(duration: number): void {
// ...
const swipeBounceBackDistance = IS_RTL ?
-RIGHT_SWIPE_BOUNCE_BACK_DISTANCE :
RIGHT_SWIPE_BOUNCE_BACK_DISTANCE;
this._animateTo(
-swipeBounceBackDistance,
duration,
this._animateToClosedPositionDuringBounce,
);
},

Maintaining Your RTL-ready App

Even after the initial RTL-compatible app release, you will likely need to iterate on new features. To improve development efficiency, I18nManager provides the forceRTL() function for faster RTL testing without changing the test device language. You might want to provide a simple switch for this in your app. Here's an example from the RTL example in the RNTester:

<RNTesterBlock title={'Quickly Test RTL Layout'}>
<View style={styles.flexDirectionRow}>
<Text style={styles.switchRowTextView}>forceRTL</Text>
<View style={styles.switchRowSwitchView}>
<Switch
onValueChange={this._onDirectionChange}
style={styles.rightAlignStyle}
value={this.state.isRTL}
/>
</View>
</View>
</RNTesterBlock>;
_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/index.html b/blog/page/5/index.html index 09403acce0f..53d2b4dfb6e 100644 --- a/blog/page/5/index.html +++ b/blog/page/5/index.html @@ -16,7 +16,7 @@ Blog · React Native - + @@ -49,7 +49,7 @@
if (module.hot) {
module.hot.accept(() => {
const nextRootReducer = require('../reducers/index').default;
store.replaceReducer(nextRootReducer);
});
}
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/tags/announcement/index.html b/blog/tags/announcement/index.html index 4b144990f43..31b372dd8cd 100644 --- a/blog/tags/announcement/index.html +++ b/blog/tags/announcement/index.html @@ -16,7 +16,7 @@ Posts tagged "announcement" · React Native - + @@ -63,7 +63,7 @@
class ScratchPad extends Component {
render() {
return (
<View style={{flex: 1}}>
<Text style={{fontSize: 30, flex: 1, textAlign: 'center'}}>
Isn't this cool?
</Text>
<Text style={{fontSize: 100, flex: 1, textAlign: 'center'}}>
👍
</Text>
</View>
);
}
}
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/index.html b/blog/tags/engineering/index.html index 6708b1a9ba4..c7ddeb45534 100644 --- a/blog/tags/engineering/index.html +++ b/blog/tags/engineering/index.html @@ -16,7 +16,7 @@ Posts tagged "engineering" · React Native - + @@ -87,7 +87,7 @@
if (module.hot) {
module.hot.accept(() => {
const nextRootReducer = require('../reducers/index').default;
store.replaceReducer(nextRootReducer);
});
}
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/index.html b/blog/tags/events/index.html index 56de63e6e93..090908bfb23 100644 --- a/blog/tags/events/index.html +++ b/blog/tags/events/index.html @@ -16,7 +16,7 @@ Posts tagged "events" · React Native - + @@ -30,7 +30,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 418215b8002..ad7648e3dfa 100644 --- a/blog/tags/index.html +++ b/blog/tags/index.html @@ -16,7 +16,7 @@ Tags · React Native - + @@ -28,7 +28,7 @@

All Blog Posts

Tags

- + diff --git a/blog/tags/release/index.html b/blog/tags/release/index.html index fef21e6a3d3..8ac4d5c73f6 100644 --- a/blog/tags/release/index.html +++ b/blog/tags/release/index.html @@ -16,7 +16,7 @@ Posts tagged "release" · React Native - + @@ -41,7 +41,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.

Announcing React Native 0.62 with Flipper

Rick Hanlon

Rick Hanlon

React Native Core at Facebook

Today we’re releasing React Native version 0.62 which includes support for Flipper by default.

This release comes in the midst of a global pandemic. We’re releasing this version today to respect the work of hundreds of contributors who made this release possible and to prevent the release from falling too far behind master. Please be mindful of the reduced capacity of contributors to help with issues and prepare to delay upgrading if necessary.

Flipper by default

Flipper is a developer tool for debugging mobile apps. It’s popular in the Android and iOS communities, and in this release we’ve enabled support by default for new and existing React Native apps.

Screenshot of Flipper for React Native

Flipper provides the following features out of the box:

Additionally, since Flipper is an extensible platform, it provides a marketplace that pulls plugins from NPM so you can publish and install custom plugins specific to your workflows. See the available plugins here.

For more information, check out the Flipper documentation.

New dark mode features

We’ve added a new Appearance module to provide access to the user's appearance preferences, such as their preferred color scheme (light or dark).

const colorScheme = Appearance.getColorScheme();
if (colorScheme === 'dark') {
// Use dark color scheme
}

We’ve also added a hook to subscribe to state updates to the users preferences:

import { Text, useColorScheme } from 'react-native';
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:

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.

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/index.html b/blog/tags/showcase/index.html index ec961a87861..f0bec3d4454 100644 --- a/blog/tags/showcase/index.html +++ b/blog/tags/showcase/index.html @@ -16,7 +16,7 @@ Posts tagged "showcase" · React Native - + @@ -30,7 +30,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/index.html b/blog/tags/videos/index.html index 711c3da2d21..64318639ea5 100644 --- a/blog/tags/videos/index.html +++ b/blog/tags/videos/index.html @@ -16,7 +16,7 @@ Posts tagged "videos" · React Native - + @@ -30,7 +30,7 @@

All Blog Posts

1 post tagged with "videos"

View All Tags
- + diff --git a/c4f5d8e4.c94d8d52.js b/c4f5d8e4.0d2283d2.js similarity index 80% rename from c4f5d8e4.c94d8d52.js rename to c4f5d8e4.0d2283d2.js index 7f567825c38..adac26ec4b0 100644 --- a/c4f5d8e4.c94d8d52.js +++ b/c4f5d8e4.0d2283d2.js @@ -1 +1 @@ -(window.webpackJsonp=window.webpackJsonp||[]).push([[709],{1001:function(e,t,a){"use strict";a.r(t);var n=a(0),r=a.n(n),l=a(1043),c=a(1070),i=a(1157),o=a(1067),m=a(1044),s=a(1031);function d(){return(d=Object.assign||function(e){for(var t=1;t=0||(r[a]=e[a]);return r}(e,t);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var h=n.createElement("g",{fill:"none",fillRule:"evenodd"},n.createElement("rect",{height:141,rx:10,stroke:"#979797",strokeWidth:3,width:183,x:48.5,y:123.5}),n.createElement("g",{transform:"matrix(-.5 .8660254 -.8660254 -.5 214.678203 71.246479)"},n.createElement("path",{d:"m0 8h.99824564 28.00175436",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.07989948c.9324575-.59631093.9356445-1.56108391 0-2.1594329l-9.914219-6.34018907c-1.860822-1.19000432-3.3693163-.37037918-3.3693163 1.83629677v11.16721752c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362967z",fill:"#999"})),n.createElement("g",{transform:"matrix(-.5 .8660254 -.8660254 -.5 124.356406 282.253521)"},n.createElement("path",{d:"m0 8h.99824564 28.00175436",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.07989948c.9324575-.59631093.9356445-1.56108391 0-2.1594329l-9.914219-6.34018907c-1.860822-1.19000432-3.3693163-.37037918-3.3693163 1.83629677v11.16721752c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362967z",fill:"#999"})),n.createElement("g",{transform:"matrix(.5 .8660254 .8660254 -.5 248.321797 71.246479)"},n.createElement("path",{d:"m0 8h.99824564 28.00175436",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.07989948c.9324575-.59631093.9356445-1.56108391 0-2.1594329l-9.914219-6.34018907c-1.860822-1.19000432-3.3693163-.37037918-3.3693163 1.83629677v11.16721752c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362967z",fill:"#999"})),n.createElement("g",{transform:"matrix(.5 .8660254 .8660254 -.5 158 282)"},n.createElement("path",{d:"m0 8h.99824564 28.00175436",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.07989948c.9324575-.59631093.9356445-1.56108391 0-2.1594329l-9.914219-6.34018907c-1.860822-1.19000432-3.3693163-.37037918-3.3693163 1.83629677v11.16721752c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362967z",fill:"#999"})),n.createElement("g",{transform:"translate(169)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:33.486328,y:33},"App.js"))),n.createElement("g",{transform:"translate(56 198)"},n.createElement("rect",{height:54,rx:8,stroke:"#4077f7",width:167,x:1.5,y:.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:27.476563,y:33},"Header.ios.js"))),n.createElement("g",{transform:"translate(56 134)"},n.createElement("rect",{height:54,rx:8,stroke:"#0ca40d",width:167,x:.5,y:.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:8.458008,y:33},"Header.android.js"))),n.createElement("g",{transform:"translate(258 122)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:28.986328,y:33},"Body.js"))),n.createElement("g",{transform:"translate(0 325)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:37.986328,y:33},"Image"))),n.createElement("g",{transform:"translate(151 325)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:45.496582,y:33},"Text"))),n.createElement("g",{transform:"translate(372 191)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:45.496582,y:33},"Text"))),n.createElement("g",{transform:"translate(372 260)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:45.496582,y:33},"Text"))),n.createElement("g",{transform:"translate(372 329)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:45.496582,y:33},"Text"))),n.createElement("g",{transform:"translate(372 397)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:45.496582,y:33},"Text"))),n.createElement("path",{d:"m201 304h241v6h-241z",fill:"#999",transform:"matrix(0 1 1 0 14.5 -14.5)"}),n.createElement("g",{transform:"matrix(1 0 0 -1 323 227)"},n.createElement("path",{d:"m0 8.5h1.49809915 27.50190085",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.57993401c.9324575-.59631093.9356445-1.56108391 0-2.15943291l-9.914219-6.34018906c-1.860822-1.19000433-3.3693163-.37037919-3.3693163 1.83629677v11.16721749c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362968z",fill:"#999"})),n.createElement("g",{transform:"matrix(1 0 0 -1 323 365)"},n.createElement("path",{d:"m0 8.5h1.49809915 27.50190085",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.57993401c.9324575-.59631093.9356445-1.56108391 0-2.15943291l-9.914219-6.34018906c-1.860822-1.19000433-3.3693163-.37037919-3.3693163 1.83629677v11.16721749c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362968z",fill:"#999"})),n.createElement("g",{transform:"matrix(1 0 0 -1 323 296)"},n.createElement("path",{d:"m0 8.5h1.49809915 27.50190085",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.57993401c.9324575-.59631093.9356445-1.56108391 0-2.15943291l-9.914219-6.34018906c-1.860822-1.19000433-3.3693163-.37037919-3.3693163 1.83629677v11.16721749c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362968z",fill:"#999"})),n.createElement("g",{transform:"matrix(1 0 0 -1 323 432)"},n.createElement("path",{d:"m0 8.5h1.49809915 27.50190085",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.57993401c.9324575-.59631093.9356445-1.56108391 0-2.15943291l-9.914219-6.34018906c-1.860822-1.19000433-3.3693163-.37037919-3.3693163 1.83629677v11.16721749c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362968z",fill:"#999"})));var f=function(e){var t=e.title,a=e.titleId,r=u(e,["title","titleId"]);return n.createElement("svg",d({viewBox:"0 0 498 452","aria-labelledby":a},r),t?n.createElement("title",{id:a},t):null,h)};function p(){var e=document.querySelector(".NativeDevelopment"),t=document.querySelector(".NativeDevelopment .dissection").children,a=t.length;function n(e,t,a){return Math.min(a,Math.max(t,e))}function r(){for(var r,l=1-n((e.getBoundingClientRect().top-60)/window.innerHeight,0,1),c=n((l-(r=.2))/(.9-r),0,1),i=0;i\n Step One\n \n Edit App.js to change this screen and turn it\n into your app.\n \n See Your Changes\n \n Press Cmd + R inside the simulator to reload\n your app\u2019s code.\n \n Debug\n \n Press Cmd + M or Shake your device to open the\n React Native Debug Menu.\n \n Learn\n \n Read the docs to discover what to do next:\n \n \n ",y="\nReact Native lets you create truly native apps and doesn't compromise your users' experiences.\nIt provides a core set of platform agnostic native components like View, Text, and Image\nthat map directly to the platform\u2019s native UI building blocks.\n ",x="\nReact components wrap existing native code and interact with native APIs via\nReact\u2019s declarative UI paradigm and JavaScript. This enables native app development\nfor whole new teams of developers, and can let existing native teams work much faster.\n ",w="\nSee your changes as soon as you save. With the power of JavaScript,\nReact Native lets you iterate at lightning speed. No more waiting for native builds to finish.\nSave, see, repeat.\n ",b="\nMembers of the React Native team frequently speak at various conferences.\n

\nYou can follow the latest news from the React Native team on Twitter\n ";function k(e){var t=e.text;return r.a.createElement("h2",{className:"Heading"},t)}function N(e){var t=e.href,a=e.type,n=void 0===a?"primary":a,l=e.target,c=e.children;return r.a.createElement("a",{className:"ActionButton "+n,href:t,target:l},c)}function T(e){var t=e.title,a=e.text,n=e.moreContent;return r.a.createElement(r.a.Fragment,null,r.a.createElement(k,{text:t}),r.a.createElement("div",{dangerouslySetInnerHTML:{__html:a}}),n)}function R(){return r.a.createElement(r.a.Fragment,null,r.a.createElement(N,{type:"primary",href:Object(m.a)("docs/getting-started"),target:"_self"},"Get started"),r.a.createElement(N,{type:"secondary",href:Object(m.a)("docs/tutorial"),target:"_self"},"Learn basics"))}function S(){return r.a.createElement("a",{href:"https://twitter.com/intent/follow?screen_name=reactnative®ion=follow_link",className:"twitter-follow-button"},r.a.createElement("div",{className:"icon"}),"Follow @reactnative")}function O(){return r.a.createElement("div",{className:"github-button"},r.a.createElement(i.a,{href:"https://github.com/facebook/react-native","data-icon":"octicon-star","data-size":"large","aria-label":"Star facebook/react-native on GitHub"},"Star"))}function W(e){var t=e.element,a=void 0===t?"section":t,n=e.children,l=e.className,c=e.background,i=void 0===c?"light":c,o=a;return r.a.createElement(o,{className:"Section "+l+" "+i},n)}function j(e){var t=e.columnOne,a=e.columnTwo,n=e.reverse;return r.a.createElement("div",{className:"TwoColumns "+(n?"reverse":"")},r.a.createElement("div",{className:"column first "+(n?"right":"left")},t),r.a.createElement("div",{className:"column last "+(n?"left":"right")},a))}function F(e){var t=e.className,a=e.fill,n=e.stroke;return r.a.createElement("rect",{className:"screen "+t,rx:"3%",width:"180",height:"300",x:"-90",y:"-150",fill:a,stroke:n})}function H(){return r.a.createElement("svg",{className:"LogoAnimation init",width:350,height:350,xmlns:"http://www.w3.org/2000/svg",viewBox:"-200 -200 400 400"},r.a.createElement("title",null,"React Logo"),r.a.createElement("clipPath",{id:"screen"},r.a.createElement(F,{fill:"none",stroke:"gray"})),r.a.createElement("rect",{x:"-25",y:"120",width:"50",height:"25",rx:"2",fill:"white",stroke:"none",className:"stand"}),r.a.createElement("polygon",{points:"-125,90 125,90 160,145 -160,145",fill:"white",stroke:"white",strokeWidth:"5",strokeLinejoin:"round",className:"base"}),r.a.createElement(F,{className:"background",stroke:"none"}),r.a.createElement("g",{clipPath:"url(#screen)",className:"logo"},r.a.createElement("g",{className:"logoInner"},r.a.createElement("circle",{cx:"0",cy:"0",r:"30",fill:"#61dafb"}),r.a.createElement("g",{stroke:"#61dafb",strokeWidth:"15",fill:"none",id:"logo"},r.a.createElement("ellipse",{rx:"165",ry:"64"}),r.a.createElement("ellipse",{rx:"165",ry:"64",transform:"rotate(60)"}),r.a.createElement("ellipse",{rx:"165",ry:"64",transform:"rotate(120)"}))),r.a.createElement("line",{x1:"-30",x2:"30",y1:"130",y2:"130",stroke:"white",strokeWidth:"8",strokeLinecap:"round",className:"speaker"})),r.a.createElement(F,{fill:"none",stroke:"white"}))}function z(){return r.a.createElement(W,{background:"dark",className:"HeaderHero"},r.a.createElement("div",{className:"socialLinks"},r.a.createElement(S,null),r.a.createElement(O,null)),r.a.createElement(j,{reverse:!0,columnOne:r.a.createElement(H,null),columnTwo:r.a.createElement(r.a.Fragment,null,r.a.createElement("h1",{className:"title"},"React Native"),r.a.createElement("p",{className:"tagline"},"Learn once, write\xa0anywhere."),r.a.createElement("div",{className:"buttons"},r.a.createElement(R,null)))}))}function L(){return r.a.createElement(W,{className:"NativeApps",background:"light"},r.a.createElement(j,{reverse:!0,columnOne:r.a.createElement(T,{title:"Create native apps for Android and iOS using React",text:E}),columnTwo:r.a.createElement("img",{alt:"",src:Object(m.a)("img/homepage/phones.png")})}))}function C(){return r.a.createElement(W,{className:"NativeCode",background:"tint"},r.a.createElement(j,{columnOne:r.a.createElement(T,{title:"Written in JavaScript\u2014rendered with native code",text:g}),columnTwo:r.a.createElement(c.a,{language:"jsx"},v)}))}function I(){return r.a.createElement(W,{className:"NativeDevelopment",background:"light"},r.a.createElement(j,{reverse:!0,columnOne:r.a.createElement(T,{title:"Native Development For Everyone",text:y}),columnTwo:r.a.createElement("div",{className:"dissection"},[0,1,2,3].map((function(e){return r.a.createElement("img",{alt:"",key:e,src:Object(m.a)("img/homepage/dissection/"+e+".png")})})))}))}function A(){return r.a.createElement(W,{className:"CrossPlatform",background:"tint"},r.a.createElement(j,{columnOne:r.a.createElement(T,{title:"Seamless Cross-Platform",text:x}),columnTwo:r.a.createElement(f,null)}))}function P(){return r.a.createElement(W,{className:"FastRefresh",background:"light"},r.a.createElement(j,{reverse:!0,columnOne:r.a.createElement(T,{title:"Fast Refresh",text:w}),columnTwo:r.a.createElement("video",{muted:!0,autoPlay:!0,loop:!0,playsInline:!0,src:Object(m.a)("img/homepage/ReactRefresh.mp4")})}))}function M(){return r.a.createElement(W,{className:"Talks",background:"tint"},r.a.createElement(j,{columnOne:r.a.createElement(T,{title:"Talks",text:b,moreContent:r.a.createElement(S,null)}),columnTwo:r.a.createElement("div",{className:"vidWrapper"},r.a.createElement("iframe",{src:"https://www.youtube.com/embed/NCAY0HIfrwc",title:"Mobile Innovation with React Native, ComponentKit, and Litho",frameBorder:"0",allow:"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture",allowFullScreen:!0}))}))}function D(){var e=Object(s.a)().siteConfig.customFields.users.filter((function(e){return e.pinned}));return r.a.createElement("ul",{className:"AppList"},e.map((function(e,t){var a=e.icon.startsWith("http")?e.icon:Object(m.a)("img/showcase/"+e.icon);return r.a.createElement("li",{key:t,className:"item"},r.a.createElement("a",{href:e.infoLink},r.a.createElement("img",{src:a,alt:e.name})))})))}function B(){return r.a.createElement(W,{className:"Community",background:"light"},r.a.createElement("div",{className:"content"},r.a.createElement(k,{text:"Facebook Supported, Community Driven"}),r.a.createElement(j,{columnOne:r.a.createElement(r.a.Fragment,null,r.a.createElement("p",{className:"firstP"},r.a.createElement("img",{src:Object(m.a)("img/homepage/fb-logo.svg"),alt:""}),r.a.createElement("span",null,"Facebook released React Native in 2015 and has been maintaining it ever since.")),r.a.createElement("p",null,"In 2018, React Native had the"," ",r.a.createElement("a",{href:"https://octoverse.github.com/2018/projects.html#repositories"},"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"," ",r.a.createElement("a",{href:"https://callstack.com/"},"Callstack"),","," ",r.a.createElement("a",{href:"https://expo.io/"},"Expo"),","," ",r.a.createElement("a",{href:"https://infinite.red/"},"Infinite Red"),","," ",r.a.createElement("a",{href:"https://www.microsoft.com/en-gb/"},"Microsoft")," and"," ",r.a.createElement("a",{href:"https://swmansion.com/"},"Software Mansion"),"."),r.a.createElement("p",null,"Our community is always shipping exciting new projects and exploring platforms beyond Android and iOS with repos like"," ",r.a.createElement("a",{href:"https://github.com/microsoft/react-native-windows#readme"},"React Native Windows"),","," ",r.a.createElement("a",{href:"https://github.com/microsoft/react-native-macos#readme"},"React Native macOS")," ","and"," ",r.a.createElement("a",{href:"https://github.com/necolas/react-native-web#readme"},"React Native Web"),".")),columnTwo:r.a.createElement(r.a.Fragment,null,r.a.createElement("p",null,"React Native is being used in thousands of apps, but it's likely you've already used it in one of these apps:"),r.a.createElement(D,null),r.a.createElement("p",null,"and ",r.a.createElement("a",{href:Object(m.a)("showcase")},"many more"),"."))})))}function J(){return r.a.createElement(W,{className:"GetStarted",background:"dark"},r.a.createElement("div",{className:"content"},r.a.createElement(k,{text:"Give it a try"}),r.a.createElement("ol",{className:"steps"},r.a.createElement("li",null,r.a.createElement("p",null,"Run this"),r.a.createElement("div",{className:"terminal"},r.a.createElement("code",null,"npx react-native init MyTestApp"))),r.a.createElement("li",null,r.a.createElement("p",null,"Read these"),r.a.createElement(R,null)))))}var _=function(){Object(n.useEffect)((function(){return function(){var e=["full","mobile","desktop","laptop","mobile2","full2"],t=[1250,1500,1500,1500,1500,1250],a=0,n=[],r=document.querySelector(".LogoAnimation");function l(){var c=e[a];r.classList.remove(c);var i=e[a=(a+1)%e.length],o=t[a];r.classList.add(i),n.push(setTimeout(l,o))}function c(){document.hidden?(n.forEach((function(e){clearTimeout(e)})),n.length=0):l()}return document.hidden||n.push(setTimeout((function(){r.classList.remove("init"),l()}),2e3)),document.addEventListener("visibilitychange",c,!1),function(){return document.removeEventListener("visibilitychange",c)}}()}),[]),Object(n.useEffect)((function(){return p()}),[])};t.default=function(){return _(),r.a.createElement(l.a,{wrapperClassName:"homepage"},r.a.createElement(o.a,null,r.a.createElement("title",null,"React Native \xb7 A framework for building native apps using React")),r.a.createElement(z,null),r.a.createElement(L,null),r.a.createElement(C,null),r.a.createElement(I,null),r.a.createElement(A,null),r.a.createElement(P,null),r.a.createElement(M,null),r.a.createElement(B,null),r.a.createElement(J,null))}}}]); \ No newline at end of file +(window.webpackJsonp=window.webpackJsonp||[]).push([[709],{1001:function(e,t,a){"use strict";a.r(t);var n=a(0),r=a.n(n),l=a(1043),c=a(1070),i=a(1157),o=a(1067),s=a(1044),m=a(1031);function d(){return(d=Object.assign||function(e){for(var t=1;t=0||(r[a]=e[a]);return r}(e,t);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var h=n.createElement("g",{fill:"none",fillRule:"evenodd"},n.createElement("rect",{height:141,rx:10,stroke:"#979797",strokeWidth:3,width:183,x:48.5,y:123.5}),n.createElement("g",{transform:"matrix(-.5 .8660254 -.8660254 -.5 214.678203 71.246479)"},n.createElement("path",{d:"m0 8h.99824564 28.00175436",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.07989948c.9324575-.59631093.9356445-1.56108391 0-2.1594329l-9.914219-6.34018907c-1.860822-1.19000432-3.3693163-.37037918-3.3693163 1.83629677v11.16721752c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362967z",fill:"#999"})),n.createElement("g",{transform:"matrix(-.5 .8660254 -.8660254 -.5 124.356406 282.253521)"},n.createElement("path",{d:"m0 8h.99824564 28.00175436",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.07989948c.9324575-.59631093.9356445-1.56108391 0-2.1594329l-9.914219-6.34018907c-1.860822-1.19000432-3.3693163-.37037918-3.3693163 1.83629677v11.16721752c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362967z",fill:"#999"})),n.createElement("g",{transform:"matrix(.5 .8660254 .8660254 -.5 248.321797 71.246479)"},n.createElement("path",{d:"m0 8h.99824564 28.00175436",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.07989948c.9324575-.59631093.9356445-1.56108391 0-2.1594329l-9.914219-6.34018907c-1.860822-1.19000432-3.3693163-.37037918-3.3693163 1.83629677v11.16721752c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362967z",fill:"#999"})),n.createElement("g",{transform:"matrix(.5 .8660254 .8660254 -.5 158 282)"},n.createElement("path",{d:"m0 8h.99824564 28.00175436",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.07989948c.9324575-.59631093.9356445-1.56108391 0-2.1594329l-9.914219-6.34018907c-1.860822-1.19000432-3.3693163-.37037918-3.3693163 1.83629677v11.16721752c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362967z",fill:"#999"})),n.createElement("g",{transform:"translate(169)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:33.486328,y:33},"App.js"))),n.createElement("g",{transform:"translate(56 198)"},n.createElement("rect",{height:54,rx:8,stroke:"#4077f7",width:167,x:1.5,y:.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:27.476563,y:33},"Header.ios.js"))),n.createElement("g",{transform:"translate(56 134)"},n.createElement("rect",{height:54,rx:8,stroke:"#0ca40d",width:167,x:.5,y:.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:8.458008,y:33},"Header.android.js"))),n.createElement("g",{transform:"translate(258 122)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:28.986328,y:33},"Body.js"))),n.createElement("g",{transform:"translate(0 325)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:37.986328,y:33},"Image"))),n.createElement("g",{transform:"translate(151 325)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:45.496582,y:33},"Text"))),n.createElement("g",{transform:"translate(372 191)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:45.496582,y:33},"Text"))),n.createElement("g",{transform:"translate(372 260)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:45.496582,y:33},"Text"))),n.createElement("g",{transform:"translate(372 329)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:45.496582,y:33},"Text"))),n.createElement("g",{transform:"translate(372 397)"},n.createElement("rect",{height:52,rx:8,stroke:"#999",strokeWidth:3,width:123,x:1.5,y:1.5}),n.createElement("text",{fill:"#3d3d3d",fontFamily:"Helvetica",fontSize:18},n.createElement("tspan",{x:45.496582,y:33},"Text"))),n.createElement("path",{d:"m201 304h241v6h-241z",fill:"#999",transform:"matrix(0 1 1 0 14.5 -14.5)"}),n.createElement("g",{transform:"matrix(1 0 0 -1 323 227)"},n.createElement("path",{d:"m0 8.5h1.49809915 27.50190085",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.57993401c.9324575-.59631093.9356445-1.56108391 0-2.15943291l-9.914219-6.34018906c-1.860822-1.19000433-3.3693163-.37037919-3.3693163 1.83629677v11.16721749c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362968z",fill:"#999"})),n.createElement("g",{transform:"matrix(1 0 0 -1 323 365)"},n.createElement("path",{d:"m0 8.5h1.49809915 27.50190085",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.57993401c.9324575-.59631093.9356445-1.56108391 0-2.15943291l-9.914219-6.34018906c-1.860822-1.19000433-3.3693163-.37037919-3.3693163 1.83629677v11.16721749c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362968z",fill:"#999"})),n.createElement("g",{transform:"matrix(1 0 0 -1 323 296)"},n.createElement("path",{d:"m0 8.5h1.49809915 27.50190085",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.57993401c.9324575-.59631093.9356445-1.56108391 0-2.15943291l-9.914219-6.34018906c-1.860822-1.19000433-3.3693163-.37037919-3.3693163 1.83629677v11.16721749c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362968z",fill:"#999"})),n.createElement("g",{transform:"matrix(1 0 0 -1 323 432)"},n.createElement("path",{d:"m0 8.5h1.49809915 27.50190085",stroke:"#999",strokeWidth:6}),n.createElement("path",{d:"m40.2835353 9.57993401c.9324575-.59631093.9356445-1.56108391 0-2.15943291l-9.914219-6.34018906c-1.860822-1.19000433-3.3693163-.37037919-3.3693163 1.83629677v11.16721749c0 2.204163 1.5041128 3.0291031 3.3693163 1.8362968z",fill:"#999"})));var f=function(e){var t=e.title,a=e.titleId,r=u(e,["title","titleId"]);return n.createElement("svg",d({viewBox:"0 0 498 452","aria-labelledby":a},r),t?n.createElement("title",{id:a},t):null,h)};function p(){var e=document.querySelector(".NativeDevelopment"),t=document.querySelector(".NativeDevelopment .dissection").children,a=t.length;function n(e,t,a){return Math.min(a,Math.max(t,e))}function r(){for(var r,l=1-n((e.getBoundingClientRect().top-60)/window.innerHeight,0,1),c=n((l-(r=.2))/(.9-r),0,1),i=0;i\n Step One\n \n Edit App.js to change this screen and turn it\n into your app.\n \n See Your Changes\n \n Press Cmd + R inside the simulator to reload\n your app\u2019s code.\n \n Debug\n \n Press Cmd + M or Shake your device to open the\n React Native Debug Menu.\n \n Learn\n \n Read the docs to discover what to do next:\n \n \n ",y="\nReact Native lets you create truly native apps and doesn't compromise your users' experiences.\nIt provides a core set of platform agnostic native components like View, Text, and Image\nthat map directly to the platform\u2019s native UI building blocks.\n ",x="\nReact components wrap existing native code and interact with native APIs via\nReact\u2019s declarative UI paradigm and JavaScript. This enables native app development\nfor whole new teams of developers, and can let existing native teams work much faster.\n ",w="\nSee your changes as soon as you save. With the power of JavaScript,\nReact Native lets you iterate at lightning speed. No more waiting for native builds to finish.\nSave, see, repeat.\n ",b="\nMembers of the React Native team frequently speak at various conferences.\n

\nYou can follow the latest news from the React Native team on Twitter\n ";function k(e){var t=e.text;return r.a.createElement("h2",{className:"Heading"},t)}function N(e){var t=e.href,a=e.type,n=void 0===a?"primary":a,l=e.target,c=e.children;return r.a.createElement("a",{className:"ActionButton "+n,href:t,target:l},c)}function T(e){var t=e.title,a=e.text,n=e.moreContent;return r.a.createElement(r.a.Fragment,null,r.a.createElement(k,{text:t}),r.a.createElement("div",{dangerouslySetInnerHTML:{__html:a}}),n)}function R(){return r.a.createElement(r.a.Fragment,null,r.a.createElement(N,{type:"primary",href:Object(s.a)("docs/getting-started"),target:"_self"},"Get started"),r.a.createElement(N,{type:"secondary",href:Object(s.a)("docs/tutorial"),target:"_self"},"Learn basics"))}function S(){return r.a.createElement("a",{href:"https://twitter.com/intent/follow?screen_name=reactnative®ion=follow_link",className:"twitter-follow-button"},r.a.createElement("div",{className:"icon"}),"Follow @reactnative")}function O(){return r.a.createElement("div",{className:"github-button"},r.a.createElement(i.a,{href:"https://github.com/facebook/react-native","data-icon":"octicon-star","data-size":"large","aria-label":"Star facebook/react-native on GitHub"},"Star"))}function W(e){var t=e.element,a=void 0===t?"section":t,n=e.children,l=e.className,c=e.background,i=void 0===c?"light":c,o=a;return r.a.createElement(o,{className:"Section "+l+" "+i},n)}function j(e){var t=e.columnOne,a=e.columnTwo,n=e.reverse;return r.a.createElement("div",{className:"TwoColumns "+(n?"reverse":"")},r.a.createElement("div",{className:"column first "+(n?"right":"left")},t),r.a.createElement("div",{className:"column last "+(n?"left":"right")},a))}function F(e){var t=e.className,a=e.fill,n=e.stroke;return r.a.createElement("rect",{className:"screen "+t,rx:"3%",width:"180",height:"300",x:"-90",y:"-150",fill:a,stroke:n})}function H(){return r.a.createElement("svg",{className:"LogoAnimation init",width:350,height:350,xmlns:"http://www.w3.org/2000/svg",viewBox:"-200 -200 400 400"},r.a.createElement("title",null,"React Logo"),r.a.createElement("clipPath",{id:"screen"},r.a.createElement(F,{fill:"none",stroke:"gray"})),r.a.createElement("rect",{x:"-25",y:"120",width:"50",height:"25",rx:"2",fill:"white",stroke:"none",className:"stand"}),r.a.createElement("polygon",{points:"-125,90 125,90 160,145 -160,145",fill:"white",stroke:"white",strokeWidth:"5",strokeLinejoin:"round",className:"base"}),r.a.createElement(F,{className:"background",stroke:"none"}),r.a.createElement("g",{clipPath:"url(#screen)",className:"logo"},r.a.createElement("g",{className:"logoInner"},r.a.createElement("circle",{cx:"0",cy:"0",r:"30",fill:"#61dafb"}),r.a.createElement("g",{stroke:"#61dafb",strokeWidth:"15",fill:"none",id:"logo"},r.a.createElement("ellipse",{rx:"165",ry:"64"}),r.a.createElement("ellipse",{rx:"165",ry:"64",transform:"rotate(60)"}),r.a.createElement("ellipse",{rx:"165",ry:"64",transform:"rotate(120)"}))),r.a.createElement("line",{x1:"-30",x2:"30",y1:"130",y2:"130",stroke:"white",strokeWidth:"8",strokeLinecap:"round",className:"speaker"})),r.a.createElement(F,{fill:"none",stroke:"white"}))}function z(){return r.a.createElement(W,{background:"dark",className:"HeaderHero"},r.a.createElement("div",{className:"socialLinks"},r.a.createElement(S,null),r.a.createElement(O,null)),r.a.createElement(j,{reverse:!0,columnOne:r.a.createElement(H,null),columnTwo:r.a.createElement(r.a.Fragment,null,r.a.createElement("h1",{className:"title"},"React Native"),r.a.createElement("p",{className:"tagline"},"Learn once, write\xa0anywhere."),r.a.createElement("div",{className:"buttons"},r.a.createElement(R,null)))}))}function L(){return r.a.createElement(W,{className:"NativeApps",background:"light"},r.a.createElement(j,{reverse:!0,columnOne:r.a.createElement(T,{title:"Create native apps for Android and iOS using React",text:E}),columnTwo:r.a.createElement("img",{alt:"",src:Object(s.a)("img/homepage/phones.png")})}))}function C(){return r.a.createElement(W,{className:"NativeCode",background:"tint"},r.a.createElement(j,{columnOne:r.a.createElement(T,{title:"Written in JavaScript\u2014rendered with native code",text:g}),columnTwo:r.a.createElement(c.a,{language:"jsx"},v)}))}function I(){return r.a.createElement(W,{className:"NativeDevelopment",background:"light"},r.a.createElement(j,{reverse:!0,columnOne:r.a.createElement(T,{title:"Native Development For Everyone",text:y}),columnTwo:r.a.createElement("div",{className:"dissection"},[0,1,2,3].map((function(e){return r.a.createElement("img",{alt:"",key:e,src:Object(s.a)("img/homepage/dissection/"+e+".png")})})))}))}function A(){return r.a.createElement(W,{className:"CrossPlatform",background:"tint"},r.a.createElement(j,{columnOne:r.a.createElement(T,{title:"Seamless Cross-Platform",text:x}),columnTwo:r.a.createElement(f,null)}))}function P(){return r.a.createElement(W,{className:"FastRefresh",background:"light"},r.a.createElement(j,{reverse:!0,columnOne:r.a.createElement(T,{title:"Fast Refresh",text:w}),columnTwo:r.a.createElement("video",{muted:!0,autoPlay:!0,loop:!0,playsInline:!0,src:Object(s.a)("img/homepage/ReactRefresh.mp4")})}))}function M(){return r.a.createElement(W,{className:"Talks",background:"tint"},r.a.createElement(j,{columnOne:r.a.createElement(T,{title:"Talks",text:b,moreContent:r.a.createElement(S,null)}),columnTwo:r.a.createElement("div",{className:"vidWrapper"},r.a.createElement("iframe",{src:"https://www.youtube.com/embed/NCAY0HIfrwc",title:"Mobile Innovation with React Native, ComponentKit, and Litho",frameBorder:"0",allow:"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture",allowFullScreen:!0}))}))}function D(){var e=Object(m.a)().siteConfig.customFields.users.filter((function(e){return e.pinned}));return r.a.createElement("ul",{className:"AppList"},e.map((function(e,t){var a=e.icon.startsWith("http")?e.icon:Object(s.a)("img/showcase/"+e.icon);return r.a.createElement("li",{key:t,className:"item"},r.a.createElement("a",{href:e.infoLink},r.a.createElement("img",{src:a,alt:e.name})))})))}function B(){return r.a.createElement(W,{className:"Community",background:"light"},r.a.createElement("div",{className:"content"},r.a.createElement(k,{text:"Facebook Supported, Community Driven"}),r.a.createElement(j,{columnOne:r.a.createElement(r.a.Fragment,null,r.a.createElement("p",{className:"firstP"},r.a.createElement("img",{src:Object(s.a)("img/homepage/fb-logo.svg"),alt:""}),r.a.createElement("span",null,"Facebook released React Native in 2015 and has been maintaining it ever since.")),r.a.createElement("p",null,"In 2018, React Native had the"," ",r.a.createElement("a",{href:"https://octoverse.github.com/2018/projects#repositories"},"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"," ",r.a.createElement("span",null,r.a.createElement("a",{href:"https://callstack.com/"},"Callstack")),","," ",r.a.createElement("span",null,r.a.createElement("a",{href:"https://expo.io/"},"Expo")),", ",r.a.createElement("a",{href:"https://infinite.red/"},"Infinite Red"),","," ",r.a.createElement("a",{href:"https://www.microsoft.com/"},"Microsoft")," and"," ",r.a.createElement("a",{href:"https://swmansion.com/"},"Software Mansion"),"."),r.a.createElement("p",null,"Our community is always shipping exciting new projects and exploring platforms beyond Android and iOS with repos like"," ",r.a.createElement("span",null,r.a.createElement("a",{href:"https://github.com/microsoft/react-native-windows#readme"},"React Native Windows")),","," ",r.a.createElement("a",{href:"https://github.com/microsoft/react-native-macos#readme"},"React Native macOS")," ","and"," ",r.a.createElement("a",{href:"https://github.com/necolas/react-native-web#readme"},"React Native Web"),".")),columnTwo:r.a.createElement(r.a.Fragment,null,r.a.createElement("p",null,"React Native is being used in thousands of apps, but it's likely you've already used it in one of these apps:"),r.a.createElement(D,null),r.a.createElement("p",null,"and ",r.a.createElement("a",{href:Object(s.a)("showcase")},"many more"),"."))})))}function J(){return r.a.createElement(W,{className:"GetStarted",background:"dark"},r.a.createElement("div",{className:"content"},r.a.createElement(k,{text:"Give it a try"}),r.a.createElement("ol",{className:"steps"},r.a.createElement("li",null,r.a.createElement("p",null,"Run this"),r.a.createElement("div",{className:"terminal"},r.a.createElement("code",null,"npx react-native init MyTestApp"))),r.a.createElement("li",null,r.a.createElement("p",null,"Read these"),r.a.createElement(R,null)))))}var _=function(){Object(n.useEffect)((function(){return function(){var e=["full","mobile","desktop","laptop","mobile2","full2"],t=[1250,1500,1500,1500,1500,1250],a=0,n=[],r=document.querySelector(".LogoAnimation");function l(){var c=e[a];r.classList.remove(c);var i=e[a=(a+1)%e.length],o=t[a];r.classList.add(i),n.push(setTimeout(l,o))}function c(){document.hidden?(n.forEach((function(e){clearTimeout(e)})),n.length=0):l()}return document.hidden||n.push(setTimeout((function(){r.classList.remove("init"),l()}),2e3)),document.addEventListener("visibilitychange",c,!1),function(){return document.removeEventListener("visibilitychange",c)}}()}),[]),Object(n.useEffect)((function(){return p()}),[])};t.default=function(){return _(),r.a.createElement(l.a,{wrapperClassName:"homepage"},r.a.createElement(o.a,null,r.a.createElement("title",null,"React Native \xb7 A framework for building native apps using React")),r.a.createElement(z,null),r.a.createElement(L,null),r.a.createElement(C,null),r.a.createElement(I,null),r.a.createElement(A,null),r.a.createElement(P,null),r.a.createElement(M,null),r.a.createElement(B,null),r.a.createElement(J,null))}}}]); \ No newline at end of file diff --git a/docs/0.60/_getting-started-linux-android/index.html b/docs/0.60/_getting-started-linux-android/index.html index a3294be842f..375280de8e8 100644 --- a/docs/0.60/_getting-started-linux-android/index.html +++ b/docs/0.60/_getting-started-linux-android/index.html @@ -16,7 +16,7 @@ _getting-started-linux-android · React Native - + @@ -31,7 +31,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 intallation 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/index.html b/docs/0.60/_getting-started-macos-android/index.html index 09a775af106..929d3efcc4a 100644 --- a/docs/0.60/_getting-started-macos-android/index.html +++ b/docs/0.60/_getting-started-macos-android/index.html @@ -16,7 +16,7 @@ _getting-started-macos-android · React Native - + @@ -31,7 +31,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 cask install 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 intallation 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/index.html b/docs/0.60/_getting-started-macos-ios/index.html index 205e3946e83..5be1b1aad4e 100644 --- a/docs/0.60/_getting-started-macos-ios/index.html +++ b/docs/0.60/_getting-started-macos-ios/index.html @@ -16,7 +16,7 @@ _getting-started-macos-ios · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/_getting-started-windows-android/index.html index adb624ca29f..ef3c1384778 100644 --- a/docs/0.60/_getting-started-windows-android/index.html +++ b/docs/0.60/_getting-started-windows-android/index.html @@ -16,7 +16,7 @@ _getting-started-windows-android · React Native - + @@ -31,7 +31,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 intallation 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/index.html b/docs/0.60/_integration-with-exisiting-apps-java/index.html index 4d329af50e2..25b95cb8a8d 100644 --- a/docs/0.60/_integration-with-exisiting-apps-java/index.html +++ b/docs/0.60/_integration-with-exisiting-apps-java/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-java · React Native - + @@ -45,7 +45,7 @@
@Override
protected void onDestroy() {
super.onDestroy();
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/index.html b/docs/0.60/_integration-with-exisiting-apps-objc/index.html index 82d01ee6933..8b5ef9a7578 100644 --- a/docs/0.60/_integration-with-exisiting-apps-objc/index.html +++ b/docs/0.60/_integration-with-exisiting-apps-objc/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-objc · React Native - + @@ -39,7 +39,7 @@
// Module name
AppRegistry.registerComponent('RNHighScores', () => RNHighScores);

RNHighScores is the name of your module that will be used when you add a view to React Native from within your iOS application.

The Magic: RCTRootView

Now that your React Native component is created via index.js, you need to add that component to a new or existing ViewController. The easiest path to take is to optionally create an event path to your component and then add that component to an existing ViewController.

We will tie our React Native component with a new native view in the ViewController that will actually contain it called RCTRootView .

1. Create an Event Path

You can add a new link on the main game menu to go to the "High Score" React Native page.

Event Path

2. Event Handler

We will now add an event handler from the menu link. A method will be added to the main ViewController of your application. This is where RCTRootView comes into play.

When you build a React Native application, you use the Metro bundler to create an index.bundle that will be served by the React Native server. Inside index.bundle will be our RNHighScore module. So, we need to point our RCTRootView to the location of the index.bundle resource (via NSURL) and tie it to the module.

We will, for debugging purposes, log that the event handler was invoked. Then, we will create a string with the location of our React Native code that exists inside the index.bundle. Finally, we will create the main RCTRootView. Notice how we provide RNHighScores as the moduleName that we created above when writing the code for our React Native component.

First import the RCTRootView header.

#import <React/RCTRootView.h>

The initialProperties are here for illustration purposes so we have some data for our high score screen. In our React Native component, we will use this.props to get access to that data.

- (IBAction)highScoreButtonPressed:(id)sender {
NSLog(@"High Score Button Pressed");
NSURL *jsCodeLocation = [NSURL URLWithString:@"http://localhost:8081/index.bundle?platform=ios"];
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/index.html b/docs/0.60/_integration-with-exisiting-apps-swift/index.html index 9aeeb8aa634..378a65c1578 100644 --- a/docs/0.60/_integration-with-exisiting-apps-swift/index.html +++ b/docs/0.60/_integration-with-exisiting-apps-swift/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-swift · React Native - + @@ -39,7 +39,7 @@
// Module name
AppRegistry.registerComponent('RNHighScores', () => RNHighScores);

RNHighScores is the name of your module that will be used when you add a view to React Native from within your iOS application.

The Magic: RCTRootView

Now that your React Native component is created via index.js, you need to add that component to a new or existing ViewController. The easiest path to take is to optionally create an event path to your component and then add that component to an existing ViewController.

We will tie our React Native component with a new native view in the ViewController that will actually contain it called RCTRootView .

1. Create an Event Path

You can add a new link on the main game menu to go to the "High Score" React Native page.

Event Path

2. Event Handler

We will now add an event handler from the menu link. A method will be added to the main ViewController of your application. This is where RCTRootView comes into play.

When you build a React Native application, you use the Metro bundler to create an index.bundle that will be served by the React Native server. Inside index.bundle will be our RNHighScore module. So, we need to point our RCTRootView to the location of the index.bundle resource (via NSURL) and tie it to the module.

We will, for debugging purposes, log that the event handler was invoked. Then, we will create a string with the location of our React Native code that exists inside the index.bundle. Finally, we will create the main RCTRootView. Notice how we provide RNHighScores as the moduleName that we created above when writing the code for our React Native component.

First import the React library.

import React

The initialProperties are here for illustration purposes so we have some data for our high score screen. In our React Native component, we will use this.props to get access to that data.

@IBAction func highScoreButtonTapped(sender : UIButton) {
NSLog("Hello")
let jsCodeLocation = URL(string: "http://localhost:8081/index.bundle?platform=ios")
let mockData:NSDictionary = ["scores":
[
["name":"Alex", "value":"42"],
["name":"Joel", "value":"10"]
]
]
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/index.html b/docs/0.60/accessibility/index.html index 8203108869a..2e501069fc0 100644 --- a/docs/0.60/accessibility/index.html +++ b/docs/0.60/accessibility/index.html @@ -16,7 +16,7 @@ Accessibility · React Native - + @@ -32,7 +32,7 @@
if (Platform.OS === 'android') {
UIManager.sendAccessibilityEvent(
findNodeHandle(this),
UIManager.AccessibilityEventTypes.typeViewFocused
);
}

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.

Testing TalkBack Support (Android)

To enable TalkBack, go to the Settings app on your Android device or emulator. Tap Accessibility, then TalkBack. Toggle the "Use service" switch to enable or disable it.

P.S. Android emulator doesn’t have TalkBack by default. To install it:

  1. Download TalkBack file here: https://google-talkback.en.uptodown.com/android
  2. Drag the downloaded .apk file into the emulator

You can use the volume key shortcut to toggle TalkBack. To turn on the volume key shortcut, go to the Settings app, then Accessibility. At the top, turn on Volume key shortcut.

To use the volume key shortcut, press both volume keys for 3 seconds to start an accessibility tool.

Additionally, if you prefer, you can toggle TalkBack via command line with:

# disable
adb shell settings put secure enabled_accessibility_services com.android.talkback/com.google.android.marvin.talkback.TalkBackService
# 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/index.html b/docs/0.60/accessibilityinfo/index.html index 5995230acc7..19baf1427e5 100644 --- a/docs/0.60/accessibilityinfo/index.html +++ b/docs/0.60/accessibilityinfo/index.html @@ -16,7 +16,7 @@ AccessibilityInfo · React Native - + @@ -37,7 +37,7 @@
_handleScreenReaderToggled = (screenReaderEnabled) => {
this.setState({ screenReaderEnabled });
};
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:

  • 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 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/index.html b/docs/0.60/actionsheetios/index.html index 72b582e1b2f..128f1774386 100644 --- a/docs/0.60/actionsheetios/index.html +++ b/docs/0.60/actionsheetios/index.html @@ -16,7 +16,7 @@ ActionSheetIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/activityindicator/index.html index b6aee6a3148..b44f253465c 100644 --- a/docs/0.60/activityindicator/index.html +++ b/docs/0.60/activityindicator/index.html @@ -16,7 +16,7 @@ ActivityIndicator · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/alert/index.html index 5f8cb1ce382..a39f8bfdb35 100644 --- a/docs/0.60/alert/index.html +++ b/docs/0.60/alert/index.html @@ -16,7 +16,7 @@ Alert · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/alertios/index.html index 3f9a6765c20..a64e6439774 100644 --- a/docs/0.60/alertios/index.html +++ b/docs/0.60/alertios/index.html @@ -16,7 +16,7 @@ AlertIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/animated/index.html index 35b86dc82d9..d0a9bab0492 100644 --- a/docs/0.60/animated/index.html +++ b/docs/0.60/animated/index.html @@ -16,7 +16,7 @@ Animated · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/animatedvalue/index.html index e6ad2f41c6b..a174b0da5c7 100644 --- a/docs/0.60/animatedvalue/index.html +++ b/docs/0.60/animatedvalue/index.html @@ -16,7 +16,7 @@ AnimatedValue · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/animatedvaluexy/index.html index 7ccf75eae1c..1140b4b6136 100644 --- a/docs/0.60/animatedvaluexy/index.html +++ b/docs/0.60/animatedvaluexy/index.html @@ -16,7 +16,7 @@ AnimatedValueXY · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/animations/index.html index b22b22a519f..0422117c4f7 100644 --- a/docs/0.60/animations/index.html +++ b/docs/0.60/animations/index.html @@ -16,7 +16,7 @@ Animations · React Native - + @@ -31,7 +31,7 @@
Version: 0.60

Animations

Animations are very important to create a great user experience. Stationary objects must overcome inertia as they start moving. Objects in motion have momentum and rarely come to a stop immediately. Animations allow you to convey physically believable motion in your interface.

React Native provides two complementary animation systems: Animated for granular and interactive control of specific values, and LayoutAnimation for animated global layout transactions.

Animated API

The Animated API is designed to concisely express a wide variety of interesting animation and interaction patterns in a very performant way. Animated focuses on declarative relationships between inputs and outputs, with configurable transforms in between, and start/stop methods to control time-based animation execution.

Animated exports six animatable component types: View, Text, Image, ScrollView, FlatList and SectionList, but you can also create your own using Animated.createAnimatedComponent().

For example, a container view that fades in when it is mounted may look like this:

Let's break down what's happening here. In the FadeInView constructor, a new Animated.Value called fadeAnim is initialized as part of state. The opacity property on the View is mapped to this animated value. Behind the scenes, the numeric value is extracted and used to set opacity.

When the component mounts, the opacity is set to 0. Then, an easing animation is started on the fadeAnim animated value, which will update all of its dependent mappings (in this case, only the opacity) on each frame as the value animates to the final value of 1.

This is done in an optimized way that is faster than calling setState and re-rendering. Because the entire configuration is declarative, we will be able to implement further optimizations that serialize the configuration and runs the animation on a high-priority thread.

Configuring animations

Animations are heavily configurable. Custom and predefined easing functions, delays, durations, decay factors, spring constants, and more can all be tweaked depending on the type of animation.

Animated provides several animation types, the most commonly used one being Animated.timing(). It supports animating a value over time using one of various predefined easing functions, or you can use your own. Easing functions are typically used in animation to convey gradual acceleration and deceleration of objects.

By default, timing will use a easeInOut curve that conveys gradual acceleration to full speed and concludes by gradually decelerating to a stop. You can specify a different easing function by passing a easing parameter. Custom duration or even a delay before the animation starts is also supported.

For example, if we want to create a 2-second long animation of an object that slightly backs up before moving to its final position:

Animated.timing(this.state.xPosition, {
toValue: 100,
easing: Easing.back(),
duration: 2000
}).start();

Take a look at the Configuring animations section of the Animated API reference to learn more about all the config parameters supported by the built-in animations.

Composing animations

Animations can be combined and played in sequence or in parallel. Sequential animations can play immediately after the previous animation has finished, or they can start after a specified delay. The Animated API provides several methods, such as sequence() and delay(), each of which take an array of animations to execute and automatically calls start()/stop() as needed.

For example, the following animation coasts to a stop, then it springs back while twirling in parallel:

Animated.sequence([
// decay, then spring to start and twirl
Animated.decay(position, {
// coast to a stop
velocity: { x: gestureState.vx, y: gestureState.vy }, // velocity from gesture release
deceleration: 0.997
}),
Animated.parallel([
// after decay, in parallel:
Animated.spring(position, {
toValue: { x: 0, y: 0 } // return to start
}),
Animated.timing(twirl, {
// and twirl
toValue: 360
})
])
]).start(); // start the sequence group

If one animation is stopped or interrupted, then all other animations in the group are also stopped. Animated.parallel has a stopTogether option that can be set to false to disable this.

You can find a full list of composition methods in the Composing animations section of the Animated API reference.

Combining animated values

You can combine two animated values via addition, multiplication, division, or modulo to make a new animated value.

There are some cases where an animated value needs to invert another animated value for calculation. An example is inverting a scale (2x --> 0.5x):

const a = new Animated.Value(1);
const b = Animated.divide(1, a);
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:

  • spring.stopAnimation(callback) will stop the animation and invoke callback with the final value. This is useful when making gesture transitions.
  • spring.addListener(callback) will invoke callback asynchronously while the animation is running, providing a recent value. This is useful for triggering state changes, for example snapping a bobble to a new option as the user drags it closer, because these larger state changes are less sensitive to a few frames of lag compared to continuous gestures like panning which need to run at 60 fps.

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/index.html b/docs/0.60/app-extensions/index.html index e88a6e2d74e..2c07d207869 100644 --- a/docs/0.60/app-extensions/index.html +++ b/docs/0.60/app-extensions/index.html @@ -16,7 +16,7 @@ App Extensions · React Native - + @@ -30,7 +30,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/appearance/index.html b/docs/0.60/appearance/index.html index d37366c0cea..50a3374041b 100644 --- a/docs/0.60/appearance/index.html +++ b/docs/0.60/appearance/index.html @@ -16,7 +16,7 @@ Appearance · React Native - + @@ -30,7 +30,7 @@
Version: 0.60

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.60/appregistry/index.html b/docs/0.60/appregistry/index.html index 2254de64c1b..f022188857f 100644 --- a/docs/0.60/appregistry/index.html +++ b/docs/0.60/appregistry/index.html @@ -16,7 +16,7 @@ AppRegistry · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/appstate/index.html index 8c36337cbe1..0a9f8995563 100644 --- a/docs/0.60/appstate/index.html +++ b/docs/0.60/appstate/index.html @@ -16,7 +16,7 @@ AppState · React Native - + @@ -35,7 +35,7 @@
_handleAppStateChange = (nextAppState) => {
if (
this.state.appState.match(/inactive|background/) &&
nextAppState === 'active'
) {
console.log('App has come to the foreground!');
}
this.setState({ appState: nextAppState });
};
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/index.html b/docs/0.60/asyncstorage/index.html index 8236977b027..208c81b6d9c 100644 --- a/docs/0.60/asyncstorage/index.html +++ b/docs/0.60/asyncstorage/index.html @@ -16,7 +16,7 @@ AsyncStorage · React Native - + @@ -38,7 +38,7 @@
AsyncStorage.multiSet(multi_set_pairs, (err) => {
AsyncStorage.multiMerge(multi_merge_pairs, (err) => {
AsyncStorage.multiGet(['UID234', 'UID345'], (err, stores) => {
stores.map((result, i, store) => {
let key = store[i][0];
let val = store[i][1];
console.log(key, val);
});
});
});
});
// 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/index.html b/docs/0.60/backandroid/index.html index bd534c20703..b23d9a1e644 100644 --- a/docs/0.60/backandroid/index.html +++ b/docs/0.60/backandroid/index.html @@ -16,7 +16,7 @@ BackAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/backhandler/index.html index 936ab37b82a..597c9567150 100644 --- a/docs/0.60/backhandler/index.html +++ b/docs/0.60/backhandler/index.html @@ -16,7 +16,7 @@ BackHandler · React Native - + @@ -34,7 +34,7 @@
handleBackPress = () => {
this.goBack(); // works best when the goBack is async
return true;
}

Lifecycle alternative:

componentDidMount() {
this.backHandler = BackHandler.addEventListener('hardwareBackPress', () => {
this.goBack(); // works best when the goBack is async
return true;
});
}
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/index.html b/docs/0.60/building-for-tv/index.html index f0be751d4bb..915139267de 100644 --- a/docs/0.60/building-for-tv/index.html +++ b/docs/0.60/building-for-tv/index.html @@ -16,7 +16,7 @@ Building For TV Devices · React Native - + @@ -35,7 +35,7 @@
componentDidMount() {
this._enableTVEventHandler();
}
componentWillUnmount() {
this._disableTVEventHandler();
}
}

  • Dev Menu support: On the simulator, cmd-M will bring up the developer menu, similar to Android. To bring it up on a real Android TV device, press the menu button or long press the fast-forward button on the remote. (Please do not shake the Android TV device, that will not work :) )

  • Known issues:

    • InputText components do not work for now (i.e. they cannot receive focus).
Edit this page
Last updated on
- + diff --git a/docs/0.60/button/index.html b/docs/0.60/button/index.html index 562bb8d29c2..3613406d701 100644 --- a/docs/0.60/button/index.html +++ b/docs/0.60/button/index.html @@ -16,7 +16,7 @@ Button · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/cameraroll/index.html index 9fba934b453..668be158080 100644 --- a/docs/0.60/cameraroll/index.html +++ b/docs/0.60/cameraroll/index.html @@ -16,7 +16,7 @@ 🚧 CameraRoll · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/checkbox/index.html index ad86c166d49..3cd2223a580 100644 --- a/docs/0.60/checkbox/index.html +++ b/docs/0.60/checkbox/index.html @@ -16,7 +16,7 @@ CheckBox · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/clipboard/index.html index a1ce9b0860a..ab3acec526a 100644 --- a/docs/0.60/clipboard/index.html +++ b/docs/0.60/clipboard/index.html @@ -16,7 +16,7 @@ Clipboard · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/colors/index.html index c534ea87c81..1304247080c 100644 --- a/docs/0.60/colors/index.html +++ b/docs/0.60/colors/index.html @@ -16,7 +16,7 @@ Color Reference · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/communication-android/index.html index 984d5f8c5aa..9363006f8da 100644 --- a/docs/0.60/communication-android/index.html +++ b/docs/0.60/communication-android/index.html @@ -16,7 +16,7 @@ Communication between native and React Native · React Native - + @@ -32,7 +32,7 @@
export default class ImageBrowserApp extends React.Component {
renderImage(imgURI) {
return <Image source={{ uri: imgURI }} />;
}
render() {
return <View>{this.props.images.map(this.renderImage)}</View>;
}
}

ReactRootView provides a read-write property appProperties. After appProperties is set, the React Native app is re-rendered with new properties. The update is only performed when the new updated properties differ from the previous ones.

Bundle updatedProps = mReactRootView.getAppProperties();
ArrayList<String> imageList = new ArrayList<String>(Arrays.asList(
"http://foo.com/bar3.png",
"http://foo.com/bar4.png"
));
updatedProps.putStringArrayList("images", imageList);
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:

  • As events can be sent from anywhere, they can introduce spaghetti-style dependencies into your project.
  • Events share namespace, which means that you may encounter some name collisions. Collisions will not be detected statically, which makes them hard to debug.
  • If you use several instances of the same React Native component and you want to distinguish them from the perspective of your event, you'll likely need to introduce identifiers and pass them along with events (you can use the native view's reactTag as an identifier).

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/index.html b/docs/0.60/communication-ios/index.html index 89cfc5bd34f..8c85bde5082 100644 --- a/docs/0.60/communication-ios/index.html +++ b/docs/0.60/communication-ios/index.html @@ -16,7 +16,7 @@ Communication between native and React Native · React Native - + @@ -41,7 +41,7 @@
#pragma mark - RCTRootViewDelegate
- (void)rootViewDidChangeIntrinsicSize:(RCTRootView *)rootView
{
CGRect newFrame = rootView.frame;
newFrame.size = rootView.intrinsicContentSize;
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/index.html b/docs/0.60/components-and-apis/index.html index f908b88c67a..ade7ee725d5 100644 --- a/docs/0.60/components-and-apis/index.html +++ b/docs/0.60/components-and-apis/index.html @@ -16,7 +16,7 @@ Components and APIs · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/custom-webview-android/index.html index f0c667a1625..ec304aeee85 100644 --- a/docs/0.60/custom-webview-android/index.html +++ b/docs/0.60/custom-webview-android/index.html @@ -16,7 +16,7 @@ Custom WebView · React Native - + @@ -57,7 +57,7 @@
_onNavigationCompleted = (event) => {
const { onNavigationCompleted } = this.props;
onNavigationCompleted && onNavigationCompleted(event);
};
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/index.html b/docs/0.60/custom-webview-ios/index.html index cce03613dac..e711927b212 100644 --- a/docs/0.60/custom-webview-ios/index.html +++ b/docs/0.60/custom-webview-ios/index.html @@ -16,7 +16,7 @@ Custom WebView · React Native - + @@ -60,7 +60,7 @@
_onNavigationCompleted = (event) => {
const { onNavigationCompleted } = this.props;
onNavigationCompleted && onNavigationCompleted(event);
};
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/index.html b/docs/0.60/datepickerandroid/index.html index 39a575ff8b7..555f9651466 100644 --- a/docs/0.60/datepickerandroid/index.html +++ b/docs/0.60/datepickerandroid/index.html @@ -16,7 +16,7 @@ DatePickerAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/datepickerios/index.html index e94be1aa96f..c9d67b36772 100644 --- a/docs/0.60/datepickerios/index.html +++ b/docs/0.60/datepickerios/index.html @@ -16,7 +16,7 @@ DatePickerIOS · React Native - + @@ -35,7 +35,7 @@
render() {
return (
<View style={styles.container}>
<DatePickerIOS
date={this.state.chosenDate}
onDateChange={this.setDate}
/>
</View>
);
}
}
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/index.html b/docs/0.60/debugging/index.html index 93423019241..abeff5251da 100644 --- a/docs/0.60/debugging/index.html +++ b/docs/0.60/debugging/index.html @@ -16,7 +16,7 @@ Debugging · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/devsettings/index.html index 014c2e24afb..689d9a6e141 100644 --- a/docs/0.60/devsettings/index.html +++ b/docs/0.60/devsettings/index.html @@ -16,7 +16,7 @@ DevSettings · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/dimensions/index.html index 806b1aec085..10dd2cceb8e 100644 --- a/docs/0.60/dimensions/index.html +++ b/docs/0.60/dimensions/index.html @@ -16,7 +16,7 @@ Dimensions · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/direct-manipulation/index.html index e91593fbeb8..5a045994734 100644 --- a/docs/0.60/direct-manipulation/index.html +++ b/docs/0.60/direct-manipulation/index.html @@ -16,7 +16,7 @@ Direct Manipulation · React Native - + @@ -31,7 +31,7 @@
Version: 0.60

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:

setOpacityTo(value) {
// Redacted: animation related code
this.refs[CHILD_REF].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={this._handlePress}>
<View style={styles.button}>
<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:

constructor(props) {
super(props);
this.state = { myButtonOpacity: 1, };
}
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:

  • x
  • y
  • width
  • height
  • pageX
  • pageY

Note that these measurements are not available until after the rendering has been completed in native. If you need the measurements as soon as possible, consider using the onLayout prop instead.

measureInWindow(callback)

Determines the location of the given view in the window and returns the values via an async callback. If the React root view is embedded in another native view, this will give you the absolute coordinates. If successful, the callback will be called with the following arguments:

  • x
  • y
  • width
  • height

measureLayout(relativeToNativeNode, onSuccess, onFail)

Like measure(), but measures the view relative 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/index.html b/docs/0.60/drawerlayoutandroid/index.html index 5fb88cf323f..e349e2587db 100644 --- a/docs/0.60/drawerlayoutandroid/index.html +++ b/docs/0.60/drawerlayoutandroid/index.html @@ -16,7 +16,7 @@ DrawerLayoutAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/easing/index.html index 057f8cac8d9..29b64518aab 100644 --- a/docs/0.60/easing/index.html +++ b/docs/0.60/easing/index.html @@ -16,7 +16,7 @@ Easing · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/enviroment-setup/index.html index 4a322535e5a..567239cfa10 100644 --- a/docs/0.60/enviroment-setup/index.html +++ b/docs/0.60/enviroment-setup/index.html @@ -16,7 +16,7 @@ Getting Started · React Native - + @@ -32,7 +32,7 @@
Version: 0.60

Getting Started

This page will help you install and build your first React Native app.

If you are new to mobile development, the easiest way to get started is with Expo CLI. Expo is a set of tools built around React Native and, while it has many features, the most relevant feature for us right now is that it can get you writing a React Native app within minutes. You will only need a recent version of Node.js and a phone or emulator. If you'd like to try out React Native directly in your web browser before installing any tools, you can try out Snack.

If you are already familiar with mobile development, you may want to use React Native CLI. It requires Xcode or Android Studio to get started. If you already have one of these tools installed, you should be able to get up and running within a few minutes. If they are not installed, you should expect to spend about an hour installing and configuring them.

Assuming that you have Node 12 LTS or greater installed, you can use npm to install the Expo CLI command line utility:

npm install -g expo-cli

Then run the following commands to create a new React Native project called "AwesomeProject":

expo init AwesomeProject
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/index.html b/docs/0.60/fast-refresh/index.html index 4e08dc9c8b3..b5f95fc3ac8 100644 --- a/docs/0.60/fast-refresh/index.html +++ b/docs/0.60/fast-refresh/index.html @@ -16,7 +16,7 @@ Fast Refresh · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/flatlist/index.html index 91a2ac0a734..a1d558bb129 100644 --- a/docs/0.60/flatlist/index.html +++ b/docs/0.60/flatlist/index.html @@ -16,7 +16,7 @@ FlatList · React Native - + @@ -31,7 +31,7 @@
Version: 0.60

FlatList

A performant interface for rendering basic, flat lists, supporting the most handy features:

  • Fully cross-platform.
  • Optional horizontal mode.
  • Configurable viewability callbacks.
  • Header support.
  • Footer support.
  • Separator support.
  • Pull to Refresh.
  • Scroll loading.
  • ScrollToIndex support.
  • Multiple column support.

If you need section support, use <SectionList>.

Basic Example:

To render multiple columns, use the numColumns prop. Using this approach instead of a flexWrap layout can prevent conflicts with the item height logic.

More complex, multi-select example demonstrating `` usage for perf optimization and avoiding bugs.

  • By passing extraData={selected} to FlatList we make sure FlatList itself will re-render when the state changes. Without setting this prop, FlatList would not know it needs to re-render any items because it is a PureComponent and the prop comparison will not show any changes.
  • keyExtractor tells the list to use the ids for the react keys instead of the default key property.

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, unless it is nested in another FlatList of same orientation.

renderItem

renderItem({ item, index, separators });

Takes an item from data and renders it into the list.

Provides additional metadata like index if you need it, as well as a more generic separators.updateProps function which let you set whatever props you want to change the rendering of either the leading separator or trailing separator in case the more common highlight and unhighlight (which set the highlighted: boolean prop) are insufficient for your use case.

TypeRequired
functionYes
  • item (Object): The item from data being rendered.
  • index (number): The index corresponding to this item in the data array.
  • separators (Object)
    • highlight (Function)
    • unhighlight (Function)
    • updateProps (Function)
      • select (enum('leading', 'trailing'))
      • newProps (Object)

Example usage:

<FlatList
ItemSeparatorComponent={Platform.OS !== 'android' && ({highlighted}) => (
<View style={[style.separator, highlighted && {marginLeft: 0}]} />
)}
data={[{title: 'Title Text', key: 'item1'}]}
renderItem={({item, index, separators}) => (
<TouchableHighlight
onPress={() => this._onPress(item)}
onShowUnderlay={separators.highlight}
onHideUnderlay={separators.unhighlight}>
<View style={{backgroundColor: 'white'}}>
<Text>{item.title}</Text>
</View>
</TouchableHighlight>
)}
/>

data

For simplicity, data is a plain array. If you want to use something else, like an immutable list, use the underlying VirtualizedList directly.

TypeRequired
arrayYes

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted and leadingItem 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
componentNo

ListEmptyComponent

Rendered when the list is empty. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListFooterComponent

Rendered at the bottom of all the items. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListFooterComponentStyle

Styling for internal View for ListFooterComponent

TypeRequired
style objectNo

ListHeaderComponent

Rendered at the top of all the items. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListHeaderComponentStyle

Styling for internal View for ListHeaderComponent

TypeRequired
style objectNo

columnWrapperStyle

Optional custom style for multi-item rows generated when numColumns > 1.

TypeRequired
style objectNo

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, index) => {length: number, offset: number, index: number}

getItemLayout is an optional optimization that allows skipping the measurement of dynamic content if you know the size (height or width) of items ahead of time. getItemLayout is efficient if you have fixed size items, for example:

getItemLayout={(data, index) => (
{length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index}
)}

Adding getItemLayout can be a great performance boost for lists of several hundred items. Remember to include separator length (height or width) in your offset calculation if you specify ItemSeparatorComponent.

TypeRequired
functionNo

horizontal

If true, renders items next to each other horizontally instead of stacked vertically.

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

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

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 falls back to using the index, like React does.

TypeRequired
functionNo

numColumns

Multiple columns can only be rendered with horizontal={false} and will zig-zag like a flexWrap layout. Items should all be the same height - masonry layouts are not supported.

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

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

onViewableItemsChanged

(info: {
viewableItems: array,
changed: array,
}) => void

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

progressViewOffset

Set this when offset is needed for the loading indicator to show correctly.

TypeRequiredPlatform
numberNoAndroid

legacyImplementation

May not have full feature parity and is meant for debugging and performance comparison.

TypeRequired
booleanNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
booleanNo

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

viewabilityConfig

See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
ViewabilityConfigNo

viewabilityConfig takes a type ViewabilityConfig an object with following properties

PropertyRequiredType
minimumViewTimeNonumber
viewAreaCoveragePercentThresholdNonumber
itemVisiblePercentThresholdNonumber
waitForInteractionNoboolean

At least one of the viewAreaCoveragePercentThreshold or itemVisiblePercentThreshold is required. This needs to be done in the constructor to avoid following error (ref):

Error: Changing viewabilityConfig on the fly is not supported`
constructor (props) {
super(props)
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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.

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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'index' (number) - The index to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position.
  • '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.

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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'item' (object) - The item to scroll to. Required.
  • 'viewPosition' (number)

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'offset' (number) - The offset to scroll to. In case of horizontal being true, the offset is the x-value, in any other case the offset is the y-value. Required.
  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.

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/index.html b/docs/0.60/flexbox/index.html index cf5a4e14f7e..7b51cc5a10c 100644 --- a/docs/0.60/flexbox/index.html +++ b/docs/0.60/flexbox/index.html @@ -16,7 +16,7 @@ Layout with Flexbox · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/geolocation/index.html index 4691dd7d2d7..a401f326acb 100644 --- a/docs/0.60/geolocation/index.html +++ b/docs/0.60/geolocation/index.html @@ -16,7 +16,7 @@ 🚧 Geolocation · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/gesture-responder-system/index.html index 59d2b7436ee..1397823d304 100644 --- a/docs/0.60/gesture-responder-system/index.html +++ b/docs/0.60/gesture-responder-system/index.html @@ -16,7 +16,7 @@ Gesture Responder System · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/getting-started/index.html index ae3d178fc38..d377730ed59 100644 --- a/docs/0.60/getting-started/index.html +++ b/docs/0.60/getting-started/index.html @@ -16,7 +16,7 @@ Introduction · React Native - + @@ -30,7 +30,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.58., 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/index.html b/docs/0.60/handling-text-input/index.html index cc0a1c229cd..2b3b67b8929 100644 --- a/docs/0.60/handling-text-input/index.html +++ b/docs/0.60/handling-text-input/index.html @@ -16,7 +16,7 @@ Handling Text Input · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/handling-touches/index.html index b45b25cca52..26df5cb59c5 100644 --- a/docs/0.60/handling-touches/index.html +++ b/docs/0.60/handling-touches/index.html @@ -16,7 +16,7 @@ Handling Touches · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/headless-js-android/index.html index 77457d9d337..db984ccc2bf 100644 --- a/docs/0.60/headless-js-android/index.html +++ b/docs/0.60/headless-js-android/index.html @@ -16,7 +16,7 @@ Headless JS · React Native - + @@ -40,7 +40,7 @@
}
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 2bdfb2923a9..052fcc4b43e 100644 --- a/docs/0.60/height-and-width/index.html +++ b/docs/0.60/height-and-width/index.html @@ -16,7 +16,7 @@ Height and Width · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/hermes/index.html index c498daa09bc..17bb1a7f47f 100644 --- a/docs/0.60/hermes/index.html +++ b/docs/0.60/hermes/index.html @@ -16,7 +16,7 @@ Using Hermes · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/image-style-props/index.html index be65b644863..f36f3607196 100644 --- a/docs/0.60/image-style-props/index.html +++ b/docs/0.60/image-style-props/index.html @@ -16,7 +16,7 @@ Image Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/image/index.html index f8e711d5d5a..08ad92712bc 100644 --- a/docs/0.60/image/index.html +++ b/docs/0.60/image/index.html @@ -16,7 +16,7 @@ Image · React Native - + @@ -33,7 +33,7 @@
// For WebP support, including animated WebP
implementation 'com.facebook.fresco:animated-webp:2.1.0'
implementation 'com.facebook.fresco:webpsupport:2.0.0'
// 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

  • Layout Props...

  • Shadow Props...

  • Transforms...

  • borderTopRightRadius: number

  • backfaceVisibility: enum('visible', 'hidden')

  • borderBottomLeftRadius: number

  • borderBottomRightRadius: number

  • borderColor: color

  • borderRadius: number

  • borderTopLeftRadius: number

  • backgroundColor: color

  • borderWidth: number

  • opacity: number

  • overflow: enum('visible', 'hidden')

  • resizeMode: Object.keys(ImageResizeMode)

  • tintColor: color

    Changes the color of all the non-transparent pixels to the tintColor.

  • overlayColor: string (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 http://frescolib.org/docs/rounded-corners-and-circles.html

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.

  • cover: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or larger than the corresponding dimension of the view (minus padding).

  • contain: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or less than the corresponding dimension of the view (minus padding).

  • stretch: Scale width and height independently, This may change the aspect ratio of the src.

  • repeat: Repeat the image to cover the frame of the view. The image will keep its size and aspect ratio, unless it is larger than the view, in which case it will be scaled down uniformly so that it is contained in the view.

  • center: Center the image in the view along both dimensions. If the image is larger than the view, scale it down uniformly so that it is contained in the view.

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.

  • auto: Use heuristics to pick between resize and scale.

  • resize: A software operation which changes the encoded image in memory before it gets decoded. This should be used instead of scale when the image is much larger than the view.

  • scale: The image gets drawn downscaled or upscaled. Compared to resize, scale is faster (usually hardware accelerated) and produces higher quality images. This should be used if the image is smaller than the view. It should also be used if the image is slightly bigger than the view.

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}:

  • 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 (which should be wrapped in the require('./path/to/image.png') function).
  • width, height - can be specified if known at build time, in which case these will be used to set the default <Image/> component dimensions.
  • scale - used 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.

If passing a number:

  • number - Opaque type returned by something like require('./image.jpg').

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/index.html b/docs/0.60/imagebackground/index.html index ec313255be2..e33df7c15c8 100644 --- a/docs/0.60/imagebackground/index.html +++ b/docs/0.60/imagebackground/index.html @@ -16,7 +16,7 @@ ImageBackground · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/imageeditor/index.html index 3a9f8bed2b7..c3341a72f74 100644 --- a/docs/0.60/imageeditor/index.html +++ b/docs/0.60/imageeditor/index.html @@ -16,7 +16,7 @@ ImageEditor · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/imagepickerios/index.html index f0b8ef18013..d79ef65c8b1 100644 --- a/docs/0.60/imagepickerios/index.html +++ b/docs/0.60/imagepickerios/index.html @@ -16,7 +16,7 @@ ImagePickerIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/images/index.html index 129973718cb..251e2b8670f 100644 --- a/docs/0.60/images/index.html +++ b/docs/0.60/images/index.html @@ -16,7 +16,7 @@ Images · React Native - + @@ -33,7 +33,7 @@
// GOOD
var icon = this.props.active
? require('./my-icon-active.png')
: require('./my-icon-inactive.png');
<Image source={icon} />;

Note that image sources required this way include size (width, height) info for the Image. If you need to scale the image dynamically (i.e. via flex), you may need to manually set { width: undefined, height: undefined } on the style attribute.

Static Non-Image Resources

The require syntax described above can be used to statically include audio, video or document files in your project as well. Most common file types are supported including .mp3, .wav, .mp4, .mov, .html and .pdf. See bundler defaults for the full list.

You can add support for other types by adding an assetExts resolver option in your Metro configuration.

A caveat is that videos must use absolute positioning instead of flexGrow, since size info is not currently passed for non-image assets. This limitation doesn't occur for videos that are linked directly into Xcode or the Assets folder for Android.

Images From Hybrid App's Resources

If you are building a hybrid app (some UIs in React Native, some UIs in platform code) you can still use images that are already bundled into the app.

For images included via Xcode asset catalogs or in the Android drawable folder, use the image name without the extension:

<Image
source={{ uri: 'app_icon' }}
style={{ width: 40, height: 40 }}
/>

For images in the Android assets folder, use the asset:/ scheme:

<Image
source={{ uri: 'asset:/app_icon.png' }}
style={{ width: 40, height: 40 }}
/>

These approaches provide no safety checks. It's up to you to guarantee that those images are available in the application. Also you have to specify image dimensions manually.

Network Images

Many of the images you will display in your app will not be available at compile time, or you will want to load some dynamically to keep the binary size down. Unlike with static resources, you will need to manually specify the dimensions of your image. It's highly recommended that you use https as well in order to satisfy App Transport Security requirements on iOS.

// GOOD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}}
style={{width: 400, height: 400}} />
// 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.

  • default: Use the native platforms default strategy.
  • reload: The data for the URL will be loaded from the originating source. No existing cache data should be used to satisfy a URL load request.
  • force-cache: The existing cached data will be used to satisfy the request, regardless of its age or expiration date. If there is no existing data in the cache corresponding the request, the data is loaded from the originating source.
  • only-if-cached: The existing cache data will be used to satisfy a request, regardless of its age or expiration date. If there is no existing data in the cache corresponding to a URL load request, no attempt is made to load the data from the originating source, and the load is considered to have failed.
<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:

  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomLeftRadius
  • borderBottomRightRadius

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/index.html b/docs/0.60/imagestore/index.html index b75878379d0..c56a4358f81 100644 --- a/docs/0.60/imagestore/index.html +++ b/docs/0.60/imagestore/index.html @@ -16,7 +16,7 @@ ImageStore · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/improvingux/index.html index a62925ad0e9..23034592c5e 100644 --- a/docs/0.60/improvingux/index.html +++ b/docs/0.60/improvingux/index.html @@ -16,7 +16,7 @@ Improving User Experience · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/inputaccessoryview/index.html index a2d215402cf..ba8b8f59c8d 100644 --- a/docs/0.60/inputaccessoryview/index.html +++ b/docs/0.60/inputaccessoryview/index.html @@ -16,7 +16,7 @@ InputAccessoryView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/integration-with-existing-apps/index.html index d49374a61e5..dea3922526a 100644 --- a/docs/0.60/integration-with-existing-apps/index.html +++ b/docs/0.60/integration-with-existing-apps/index.html @@ -16,7 +16,7 @@ Integration with Existing Apps · React Native - + @@ -45,7 +45,7 @@
@Override
protected void onDestroy() {
super.onDestroy();
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/index.html b/docs/0.60/interactionmanager/index.html index 4c6f94332eb..4792c9e50e0 100644 --- a/docs/0.60/interactionmanager/index.html +++ b/docs/0.60/interactionmanager/index.html @@ -16,7 +16,7 @@ InteractionManager · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/intro-react-native-components/index.html index 2872a14fdaa..18903f24256 100644 --- a/docs/0.60/intro-react-native-components/index.html +++ b/docs/0.60/intro-react-native-components/index.html @@ -16,7 +16,7 @@ Core Components and Native Components · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/intro-react/index.html index 025ea25a4e0..6e274d459fa 100644 --- a/docs/0.60/intro-react/index.html +++ b/docs/0.60/intro-react/index.html @@ -16,7 +16,7 @@ React Fundamentals · React Native - + @@ -31,7 +31,7 @@
Version: 0.60

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:

const 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:

const 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:

const Cat = () => {
return <Text>Hello, I am your cat!</Text>;
};
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/index.html b/docs/0.60/javascript-environment/index.html index b7e54ab7b14..89d98ada33d 100644 --- a/docs/0.60/javascript-environment/index.html +++ b/docs/0.60/javascript-environment/index.html @@ -16,7 +16,7 @@ JavaScript Environment · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/keyboard/index.html index 32a5ffb47f1..64e7a56c43f 100644 --- a/docs/0.60/keyboard/index.html +++ b/docs/0.60/keyboard/index.html @@ -16,7 +16,7 @@ Keyboard · React Native - + @@ -35,7 +35,7 @@
_keyboardDidHide() {
alert('Keyboard Hidden');
}
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:

  • keyboardWillShow
  • keyboardDidShow
  • keyboardWillHide
  • keyboardDidHide
  • keyboardWillChangeFrame
  • keyboardDidChangeFrame

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/index.html b/docs/0.60/keyboardavoidingview/index.html index 1bb3a5744fa..e633d541661 100644 --- a/docs/0.60/keyboardavoidingview/index.html +++ b/docs/0.60/keyboardavoidingview/index.html @@ -16,7 +16,7 @@ KeyboardAvoidingView · React Native - + @@ -31,7 +31,7 @@
Version: 0.60

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 position of the keyboard.

Example usage:

import { KeyboardAvoidingView } from 'react-native';
<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/index.html b/docs/0.60/layout-props/index.html index 722861101e4..3c7309b9595 100644 --- a/docs/0.60/layout-props/index.html +++ b/docs/0.60/layout-props/index.html @@ -16,7 +16,7 @@ Layout Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/layoutanimation/index.html index 5cddb155d52..53e7c2d7629 100644 --- a/docs/0.60/layoutanimation/index.html +++ b/docs/0.60/layoutanimation/index.html @@ -16,7 +16,7 @@ LayoutAnimation · React Native - + @@ -31,7 +31,7 @@
Version: 0.60

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 calling setState.

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 usage:

import React, { Component } from 'react';
import {
View,
Text,
TouchableOpacity,
Platform,
UIManager
} from 'react-native';
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.

  • 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:

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/index.html b/docs/0.60/libraries/index.html index d4f5d02a2ad..52ced3bb2df 100644 --- a/docs/0.60/libraries/index.html +++ b/docs/0.60/libraries/index.html @@ -16,7 +16,7 @@ Using Libraries · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/linking-libraries-ios/index.html index 65985a698a4..c626a331b4f 100644 --- a/docs/0.60/linking-libraries-ios/index.html +++ b/docs/0.60/linking-libraries-ios/index.html @@ -16,7 +16,7 @@ Linking Libraries · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/linking/index.html index 8c13098171a..480edd09aef 100644 --- a/docs/0.60/linking/index.html +++ b/docs/0.60/linking/index.html @@ -16,7 +16,7 @@ Linking · React Native - + @@ -32,7 +32,7 @@
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
return [RCTLinkingManager application:application openURL:url options:options];
}

If you're targeting iOS 8.x or older, you can use the following code instead:

// iOS 8.x or older
#import <React/RCTLinkingManager.h>
- (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/index.html b/docs/0.60/listview/index.html index 778d878cafe..67f67a48a74 100644 --- a/docs/0.60/listview/index.html +++ b/docs/0.60/listview/index.html @@ -16,7 +16,7 @@ ListView · React Native - + @@ -31,7 +31,7 @@
Version: 0.60

ListView

DEPRECATED - use one of the new list components, such as FlatList or SectionList for bounded memory use, fewer bugs, better performance, an easier to use API, and more features. Check out this blog post for more details.

ListView - A core component designed for efficient display of vertically scrolling lists of changing data. The minimal API is to create a ListView.DataSource, populate it with a flat array of data blobs, and instantiate a ListView component with that data source and a renderRow callback which takes a blob from the data array and returns a renderable component.

Minimal example:

class MyComponent extends Component {
constructor() {
super();
const ds = new ListView.DataSource({
rowHasChanged: (r1, r2) => r1 !== r2
});
this.state = {
dataSource: ds.cloneWithRows(['row 1', 'row 2'])
};
}
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:

  • Only re-render changed rows - the rowHasChanged function provided to the data source tells the ListView if it needs to re-render a row because the source data has changed - see ListViewDataSource for more details.

  • Rate-limited row rendering - By default, only one row is rendered per event-loop (customizable with the pageSize prop). This breaks up the work into smaller chunks to reduce the chance of dropping frames while rendering rows.

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/index.html b/docs/0.60/listviewdatasource/index.html index bbf90531883..f442367ed69 100644 --- a/docs/0.60/listviewdatasource/index.html +++ b/docs/0.60/listviewdatasource/index.html @@ -16,7 +16,7 @@ ListViewDataSource · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/maskedviewios/index.html index d266702d31f..6826c598fef 100644 --- a/docs/0.60/maskedviewios/index.html +++ b/docs/0.60/maskedviewios/index.html @@ -16,7 +16,7 @@ 🚧 MaskedViewIOS · React Native - + @@ -31,7 +31,7 @@
Version: 0.60

🚧 MaskedViewIOS

Deprecated. Use @react-native-community/masked-view instead.

Renders the child view with a mask specified in the maskElement prop.

Example

import React from 'react';
import { MaskedViewIOS, Text, View } from 'react-native';
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/index.html b/docs/0.60/modal/index.html index 91f01bdced8..470f87f74fa 100644 --- a/docs/0.60/modal/index.html +++ b/docs/0.60/modal/index.html @@ -16,7 +16,7 @@ Modal · React Native - + @@ -35,7 +35,7 @@
<TouchableHighlight
onPress={() => {
this.setModalVisible(!this.state.modalVisible);
}}>
<Text>Hide Modal</Text>
</TouchableHighlight>
</View>
</View>
</Modal>
<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.

  • 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

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

animated

Deprecated. Use the animationType prop instead.

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 3022d4a084c..fe1f200bb42 100644 --- a/docs/0.60/more-resources/index.html +++ b/docs/0.60/more-resources/index.html @@ -16,7 +16,7 @@ More Resources · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/native-components-android/index.html index 43ba19f1d0c..b13e29ae6b6 100644 --- a/docs/0.60/native-components-android/index.html +++ b/docs/0.60/native-components-android/index.html @@ -16,7 +16,7 @@ Native UI Components · React Native - + @@ -39,7 +39,7 @@
class MyCustomView extends React.Component {
constructor(props) {
super(props);
this._onChange = this._onChange.bind(this);
}
_onChange(event: Event) {
if (!this.props.onChangeMessage) {
return;
}
this.props.onChangeMessage(event.nativeEvent.message);
}
render() {
return <RCTMyCustomView {...this.props} onChange={this._onChange} />;
}
}
MyCustomView.propTypes = {
/**
* Callback that is called continuously when the user is dragging the map.
*/
onChangeMessage: PropTypes.func,
...
};
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
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 678f0917101..902e8ec4a4e 100644 --- a/docs/0.60/native-components-ios/index.html +++ b/docs/0.60/native-components-ios/index.html @@ -16,7 +16,7 @@ Native UI Components · React Native - + @@ -93,7 +93,7 @@
- (NSDictionary *)constantsToExport
{
UIDatePicker *dp = [[UIDatePicker alloc] init];
[dp layoutIfNeeded];
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/index.html b/docs/0.60/native-modules-android/index.html index cbabe4b0f64..935f55c3f35 100644 --- a/docs/0.60/native-modules-android/index.html +++ b/docs/0.60/native-modules-android/index.html @@ -16,7 +16,7 @@ Native Modules · React Native - + @@ -80,7 +80,7 @@
@Override
public void onHostPause() {
// Activity `onPause`
}
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}
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 03ee271625c..61232996bed 100644 --- a/docs/0.60/native-modules-ios/index.html +++ b/docs/0.60/native-modules-ios/index.html @@ -16,7 +16,7 @@ Native Modules · React Native - + @@ -68,7 +68,7 @@
RCT_EXTERN_METHOD(addEvent:(NSString *)name location:(NSString *)location date:(nonnull NSNumber *)date)
@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/index.html b/docs/0.60/native-modules-setup/index.html index 58f49cc3c95..5e4e036a7f3 100644 --- a/docs/0.60/native-modules-setup/index.html +++ b/docs/0.60/native-modules-setup/index.html @@ -16,7 +16,7 @@ Native Modules Setup · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/navigation/index.html index d42432f46ea..44ec1004146 100644 --- a/docs/0.60/navigation/index.html +++ b/docs/0.60/navigation/index.html @@ -16,7 +16,7 @@ Navigating Between Screens · React Native - + @@ -33,7 +33,7 @@
const Stack = createStackNavigator();
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/index.html b/docs/0.60/netinfo/index.html index 2efa2e3fc2a..f6b2741a781 100644 --- a/docs/0.60/netinfo/index.html +++ b/docs/0.60/netinfo/index.html @@ -16,7 +16,7 @@ NetInfo · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/network/index.html index 49616f2e1cf..c4cc13ee01b 100644 --- a/docs/0.60/network/index.html +++ b/docs/0.60/network/index.html @@ -16,7 +16,7 @@ Networking · React Native - + @@ -36,7 +36,7 @@
ws.onerror = (e) => {
// an error occurred
console.log(e.message);
};
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

  • redirect:manual
  • credentials:omit
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 bf48f95f28d..304561481f2 100644 --- a/docs/0.60/optimizing-flatlist-configuration/index.html +++ b/docs/0.60/optimizing-flatlist-configuration/index.html @@ -16,7 +16,7 @@ Optimizing Flatlist Configuration · React Native - + @@ -33,7 +33,7 @@
<FlatList
data={items}
renderItem={renderItem}
/>
// ...
}
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 b78419043b2..6674f05eed4 100644 --- a/docs/0.60/out-of-tree-platforms/index.html +++ b/docs/0.60/out-of-tree-platforms/index.html @@ -16,7 +16,7 @@ Out-of-Tree Platforms · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/panresponder/index.html index 4365850aa7e..8196b322bae 100644 --- a/docs/0.60/panresponder/index.html +++ b/docs/0.60/panresponder/index.html @@ -16,7 +16,7 @@ PanResponder · React Native - + @@ -32,7 +32,7 @@
onPanResponderGrant: (evt, gestureState) => {
// The gesture has started. Show visual feedback so the user knows
// what is happening!
// gestureState.d{x,y} will be set to zero now
},
onPanResponderMove: (evt, gestureState) => {
// The most recent move distance is gestureState.move{X,Y}
// The accumulated gesture distance since becoming responder is
// gestureState.d{x,y}
},
onPanResponderTerminationRequest: (evt, gestureState) =>
true,
onPanResponderRelease: (evt, gestureState) => {
// The user has released all touches while this view is the
// responder. This typically means a gesture has succeeded
},
onPanResponderTerminate: (evt, gestureState) => {
// Another component has become the responder, so this gesture
// should be cancelled
},
onShouldBlockNativeResponder: (evt, gestureState) => {
// Returns whether this component should block native components from becoming the JS
// responder. Returns true by default. Is currently only supported on android.
return true;
}
});
}
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:

  • onMoveShouldSetPanResponder: (e, gestureState) => {...}
  • onMoveShouldSetPanResponderCapture: (e, gestureState) => {...}
  • onStartShouldSetPanResponder: (e, gestureState) => {...}
  • onStartShouldSetPanResponderCapture: (e, gestureState) => {...}
  • onPanResponderReject: (e, gestureState) => {...}
  • onPanResponderGrant: (e, gestureState) => {...}
  • onPanResponderStart: (e, gestureState) => {...}
  • onPanResponderEnd: (e, gestureState) => {...}
  • onPanResponderRelease: (e, gestureState) => {...}
  • onPanResponderMove: (e, gestureState) => {...}
  • onPanResponderTerminate: (e, gestureState) => {...}
  • onPanResponderTerminationRequest: (e, gestureState) => {...}
  • onShouldBlockNativeResponder: (e, gestureState) => {...}

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/index.html b/docs/0.60/performance/index.html index f803bef2347..3dc95458536 100644 --- a/docs/0.60/performance/index.html +++ b/docs/0.60/performance/index.html @@ -16,7 +16,7 @@ Performance · React Native - + @@ -42,7 +42,7 @@
const config = {
transformer: {
getTransformOptions: () => {
const moduleMap = {};
modulePaths.forEach(path => {
if (fs.existsSync(path)) {
moduleMap[resolve(path)] = true;
}
});
return {
preloadedModules: moduleMap,
transform: { inlineRequires: { blacklist: moduleMap } },
};
},
},
projectRoot:ROOT_FOLDER,
};
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/index.html b/docs/0.60/permissionsandroid/index.html index e7f9dc77b56..9f243f2b1f3 100644 --- a/docs/0.60/permissionsandroid/index.html +++ b/docs/0.60/permissionsandroid/index.html @@ -16,7 +16,7 @@ PermissionsAndroid · React Native - + @@ -31,7 +31,7 @@
Version: 0.60

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

import { PermissionsAndroid } from 'react-native';
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:

  • 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.60/picker-item/index.html b/docs/0.60/picker-item/index.html index 7af7bedb7c2..88da5a507be 100644 --- a/docs/0.60/picker-item/index.html +++ b/docs/0.60/picker-item/index.html @@ -16,7 +16,7 @@ Picker.Item · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/picker-style-props/index.html index 2e4af8b5149..b74f00e349c 100644 --- a/docs/0.60/picker-style-props/index.html +++ b/docs/0.60/picker-style-props/index.html @@ -16,7 +16,7 @@ Picker Style Props · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.60/picker/index.html b/docs/0.60/picker/index.html index 343db21d52a..4bd584cd90f 100644 --- a/docs/0.60/picker/index.html +++ b/docs/0.60/picker/index.html @@ -16,7 +16,7 @@ Picker · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/pickerios/index.html index fc02acf78f6..d8cf186b60c 100644 --- a/docs/0.60/pickerios/index.html +++ b/docs/0.60/pickerios/index.html @@ -16,7 +16,7 @@ PickerIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/pixelratio/index.html index 9fb07260818..3e5a643fec0 100644 --- a/docs/0.60/pixelratio/index.html +++ b/docs/0.60/pixelratio/index.html @@ -16,7 +16,7 @@ PixelRatio · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/platform-specific-code/index.html index 11be17a53d9..c5e31ea7008 100644 --- a/docs/0.60/platform-specific-code/index.html +++ b/docs/0.60/platform-specific-code/index.html @@ -16,7 +16,7 @@ Platform Specific Code · React Native - + @@ -35,7 +35,7 @@
if (Platform.Version === 25) {
console.log('Running on Nougat!');
}

Detecting the iOS version

On iOS, the Version is a result of -[UIDevice systemVersion], which is a string with the current version of the operating system. An example of the system version is "10.3". For example, to detect the major version number on iOS:

import { Platform } from 'react-native';
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/index.html b/docs/0.60/profiling/index.html index fe3c0ecc96b..96e7327d815 100644 --- a/docs/0.60/profiling/index.html +++ b/docs/0.60/profiling/index.html @@ -16,7 +16,7 @@ Profiling · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/progressbarandroid/index.html index c18744dc609..a8e1b9da2dc 100644 --- a/docs/0.60/progressbarandroid/index.html +++ b/docs/0.60/progressbarandroid/index.html @@ -16,7 +16,7 @@ ProgressBarAndroid · React Native - + @@ -32,7 +32,7 @@
export default class App extends Component {
render() {
return (
<View style={styles.container}>
<ProgressBarAndroid />
<ProgressBarAndroid styleAttr="Horizontal" />
<ProgressBarAndroid
styleAttr="Horizontal"
color="#2196F3"
/>
<ProgressBarAndroid
styleAttr="Horizontal"
indeterminate={false}
progress={0.5}
/>
</View>
);
}
}
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:

  • 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.60/progressviewios/index.html b/docs/0.60/progressviewios/index.html index 47d2ddd7eee..340c336f8f2 100644 --- a/docs/0.60/progressviewios/index.html +++ b/docs/0.60/progressviewios/index.html @@ -16,7 +16,7 @@ ProgressViewIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/props/index.html index 6ef4e9d61ee..29da297107c 100644 --- a/docs/0.60/props/index.html +++ b/docs/0.60/props/index.html @@ -16,7 +16,7 @@ Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/publishing-forks/index.html index b85300d775d..679c29cf159 100644 --- a/docs/0.60/publishing-forks/index.html +++ b/docs/0.60/publishing-forks/index.html @@ -16,7 +16,7 @@ Publish your own version of react native · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/publishing-to-app-store/index.html index d13ec23a1b9..d9395c18141 100644 --- a/docs/0.60/publishing-to-app-store/index.html +++ b/docs/0.60/publishing-to-app-store/index.html @@ -16,7 +16,7 @@ Publishing to Apple App Store · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/pushnotificationios/index.html index 34b104457d6..44241cabc21 100644 --- a/docs/0.60/pushnotificationios/index.html +++ b/docs/0.60/pushnotificationios/index.html @@ -16,7 +16,7 @@ PushNotificationIOS · React Native - + @@ -33,7 +33,7 @@
return YES;
}
//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:

  • alertBody : The message displayed in the notification alert.
  • alertTitle : The text displayed as the title of the notification alert.
  • alertAction : The "action" displayed beneath an actionable notification. Defaults to "view";
  • soundName : The sound played when the notification is fired (optional).
  • isSilent : If true, the notification will appear without sound (optional).
  • category : The category of this notification, required for actionable notifications (optional).
  • userInfo : An optional object containing additional notification data.
  • applicationIconBadgeNumber (optional) : The number to display as the app's icon badge. The default value of this property is 0, which means that no badge is displayed.

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

  • fireDate : The date and time when the system should deliver the notification.
  • alertTitle : The text displayed as the title of the notification alert.
  • alertBody : The message displayed in the notification alert.
  • alertAction : The "action" displayed beneath an actionable notification. Defaults to "view";
  • soundName : The sound played when the notification is fired (optional).
  • isSilent : If true, the notification will appear without sound (optional).
  • category : The category of this notification, required for actionable notifications (optional).
  • userInfo : An optional object containing additional notification data.
  • applicationIconBadgeNumber (optional) : The number to display as the app's icon badge. Setting the number to 0 removes the icon badge.
  • repeatInterval : The interval to repeat as a string. Possible values: minute, hour, day, week, month, year.

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:

  • identifier : The identifier of this notification.
  • title : The title of this notification.
  • body : The body of this notification.
  • category : The category of this notification, if has one.
  • userInfo : An optional object containing additional notification data.
  • thread-id : The thread identifier of this notification, if has one.

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:

  • notification : Fired when a remote notification is received. The handler will be invoked with an instance of PushNotificationIOS.
  • localNotification : Fired when a local notification is received. The handler will be invoked with an instance of PushNotificationIOS.
  • register: Fired when the user registers for remote notifications. The handler will be invoked with a hex string representing the deviceToken.
  • registrationError: Fired when the user fails to register for remote notifications. Typically occurs when APNS is having issues, or the device is a simulator. The handler will be invoked with {message: string, code: number, details: any}.

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:

  • alert
  • badge
  • sound

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:

  • alert :boolean
  • badge :boolean
  • sound :boolean

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/index.html b/docs/0.60/ram-bundles-inline-requires/index.html index 623e4ce70b9..0f4ebe9e8d0 100644 --- a/docs/0.60/ram-bundles-inline-requires/index.html +++ b/docs/0.60/ram-bundles-inline-requires/index.html @@ -16,7 +16,7 @@ RAM Bundles and Inline Requires · React Native - + @@ -42,7 +42,7 @@
const config = {
transformer: {
getTransformOptions: () => {
const moduleMap = {};
modulePaths.forEach((path) => {
if (fs.existsSync(path)) {
moduleMap[resolve(path)] = true;
}
});
return {
preloadedModules: moduleMap,
transform: { inlineRequires: { blacklist: moduleMap } }
};
}
},
projectRoot: ROOT_FOLDER
};
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/index.html b/docs/0.60/react-node/index.html index b099ce3178b..df26c933e54 100644 --- a/docs/0.60/react-node/index.html +++ b/docs/0.60/react-node/index.html @@ -16,7 +16,7 @@ React Node Object Type · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/refreshcontrol/index.html index f4b5fd670de..f6ab948ec29 100644 --- a/docs/0.60/refreshcontrol/index.html +++ b/docs/0.60/refreshcontrol/index.html @@ -16,7 +16,7 @@ RefreshControl · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/removing-default-permissions/index.html index bafaab42533..fb7ee290478 100644 --- a/docs/0.60/removing-default-permissions/index.html +++ b/docs/0.60/removing-default-permissions/index.html @@ -16,7 +16,7 @@ Removing Default Permissions · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/running-on-device/index.html index 5c8e34c8e58..1ca882464bc 100644 --- a/docs/0.60/running-on-device/index.html +++ b/docs/0.60/running-on-device/index.html @@ -16,7 +16,7 @@ Running On Device · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/running-on-simulator-ios/index.html index 974de75eed2..445fbb246dc 100644 --- a/docs/0.60/running-on-simulator-ios/index.html +++ b/docs/0.60/running-on-simulator-ios/index.html @@ -16,7 +16,7 @@ Running On Simulator · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/safeareaview/index.html index 0ef8edef25e..9227b34217e 100644 --- a/docs/0.60/safeareaview/index.html +++ b/docs/0.60/safeareaview/index.html @@ -16,7 +16,7 @@ SafeAreaView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/scrollview/index.html index 07125833089..9055f2d3540 100644 --- a/docs/0.60/scrollview/index.html +++ b/docs/0.60/scrollview/index.html @@ -16,7 +16,7 @@ ScrollView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/sectionlist/index.html index 9532603a4e3..371695af2c4 100644 --- a/docs/0.60/sectionlist/index.html +++ b/docs/0.60/sectionlist/index.html @@ -16,7 +16,7 @@ SectionList · React Native - + @@ -30,7 +30,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, function, 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 Class, a render function, or a rendered element.

TypeRequired
[component, function, element]No

ListFooterComponent

Rendered at the very end of the list. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
[component, function, element]No

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, 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, function, 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/index.html b/docs/0.60/segmentedcontrolios/index.html index 9a918d4aac3..2e544603a3c 100644 --- a/docs/0.60/segmentedcontrolios/index.html +++ b/docs/0.60/segmentedcontrolios/index.html @@ -16,7 +16,7 @@ SegmentedControlIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/settings/index.html index c9609827321..af1317e4944 100644 --- a/docs/0.60/settings/index.html +++ b/docs/0.60/settings/index.html @@ -16,7 +16,7 @@ Settings · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/shadow-props/index.html index 44c0f35767f..c9adf3f6ea1 100644 --- a/docs/0.60/shadow-props/index.html +++ b/docs/0.60/shadow-props/index.html @@ -16,7 +16,7 @@ Shadow Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/share/index.html index e5c3db6750d..dd7a21a52a7 100644 --- a/docs/0.60/share/index.html +++ b/docs/0.60/share/index.html @@ -16,7 +16,7 @@ Share · React Native - + @@ -33,7 +33,7 @@
if (result.action === Share.sharedAction) {
if (result.activityType) {
// shared with activity type of result.activityType
} else {
// shared
}
} else if (result.action === Share.dismissedAction) {
// dismissed
}
} catch (error) {
alert(error.message);
}
};
render() {
return <Button onPress={this.onShare} title="Share" />;
}
}
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 414b0751bfb..3a216009462 100644 --- a/docs/0.60/signed-apk-android/index.html +++ b/docs/0.60/signed-apk-android/index.html @@ -16,7 +16,7 @@ Publishing to Google Play Store · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/slider/index.html index 790b400a4aa..019608a3346 100644 --- a/docs/0.60/slider/index.html +++ b/docs/0.60/slider/index.html @@ -16,7 +16,7 @@ Slider · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/snapshotviewios/index.html index 321e7d1b2b0..3f02b75a95d 100644 --- a/docs/0.60/snapshotviewios/index.html +++ b/docs/0.60/snapshotviewios/index.html @@ -16,7 +16,7 @@ SnapshotViewIOS · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.60/state/index.html b/docs/0.60/state/index.html index 282f2c34e8f..d9ce5828c94 100644 --- a/docs/0.60/state/index.html +++ b/docs/0.60/state/index.html @@ -16,7 +16,7 @@ State · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/statusbar/index.html index 311ef20f7bc..acbe5a2a56b 100644 --- a/docs/0.60/statusbar/index.html +++ b/docs/0.60/statusbar/index.html @@ -16,7 +16,7 @@ StatusBar · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/statusbarios/index.html index 41d40957fc9..3caafb80cbd 100644 --- a/docs/0.60/statusbarios/index.html +++ b/docs/0.60/statusbarios/index.html @@ -16,7 +16,7 @@ StatusBarIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/style/index.html index 3bdbdef2be9..f8b7c5eefab 100644 --- a/docs/0.60/style/index.html +++ b/docs/0.60/style/index.html @@ -16,7 +16,7 @@ Style · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/stylesheet/index.html index a72c9059306..1ceefd4e5c4 100644 --- a/docs/0.60/stylesheet/index.html +++ b/docs/0.60/stylesheet/index.html @@ -16,7 +16,7 @@ StyleSheet · React Native - + @@ -32,7 +32,7 @@
StyleSheet.flatten([styles.listItem, styles.selectedListItem]);
// returns { flex: 1, fontSize: 16, color: 'green' }

Alternative use:

var styles = StyleSheet.create({
listItem: {
flex: 1,
fontSize: 16,
color: 'white'
},
selectedListItem: {
color: 'green'
}
});
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/index.html b/docs/0.60/switch/index.html index b73b33cb3df..7bf78b3bb8f 100644 --- a/docs/0.60/switch/index.html +++ b/docs/0.60/switch/index.html @@ -16,7 +16,7 @@ Switch · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/symbolication/index.html index 31a350b1ade..bfbed033aaf 100644 --- a/docs/0.60/symbolication/index.html +++ b/docs/0.60/symbolication/index.html @@ -16,7 +16,7 @@ Symbolicating a stack trace · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/systrace/index.html index 6b87304ffc2..3bab40b0a40 100644 --- a/docs/0.60/systrace/index.html +++ b/docs/0.60/systrace/index.html @@ -16,7 +16,7 @@ Systrace · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/tabbarios-item/index.html index 27e18bd76ef..412937ebf65 100644 --- a/docs/0.60/tabbarios-item/index.html +++ b/docs/0.60/tabbarios-item/index.html @@ -16,7 +16,7 @@ TabBarIOS.Item · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/tabbarios/index.html index 7e0f88681d4..09e2821a2fd 100644 --- a/docs/0.60/tabbarios/index.html +++ b/docs/0.60/tabbarios/index.html @@ -16,7 +16,7 @@ TabBarIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/testing-overview/index.html index 247607368f6..d153637de35 100644 --- a/docs/0.60/testing-overview/index.html +++ b/docs/0.60/testing-overview/index.html @@ -16,7 +16,7 @@ Testing · React Native - + @@ -34,7 +34,7 @@
fireEvent.changeText(
getByPlaceholder('Enter grocery item'),
'banana'
);
fireEvent.press(getByText('Add the item to list'));
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:

  • For you as a developer or reviewer, it can be hard to tell whether a change in snapshot is intended or whether it's evidence of a bug. Especially large snapshots can quickly become hard to understand and their added value becomes low.
  • When snapshot is created, at that point it is considered to be correct-even in the case when the rendered output is actually wrong.
  • When a snapshot fails, it's tempting to update it using the --updateSnapshot jest option without taking proper care to investigate whether the change is expected. Certain developer discipline is thus needed.

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:

  • writing them is more time consuming compared to the other types of tests
  • they are slower to run
  • they are more prone to flakiness (a "flaky" test is a test which randomly passes and fails without any change to code)

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/index.html b/docs/0.60/text-style-props/index.html index b6f0404c16e..a623316dd48 100644 --- a/docs/0.60/text-style-props/index.html +++ b/docs/0.60/text-style-props/index.html @@ -16,7 +16,7 @@ Text Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/text/index.html index 61972587027..3ca61c64859 100644 --- a/docs/0.60/text/index.html +++ b/docs/0.60/text/index.html @@ -16,7 +16,7 @@ Text · React Native - + @@ -34,7 +34,7 @@
// otherwise, the text will flow in its own block
// |First part |
// |and |
// |second part|

Limited Style Inheritance

On the web, the usual way to set a font family and size for the entire document is to take advantage of inherited CSS properties like so:

html {
font-family: 'lucida grande', tahoma, verdana, arial, sans-serif;
font-size: 11px;
color: #141823;
}

All elements in the document will inherit this font unless they or one of their parents specifies a new rule.

In React Native, we are more strict about it: you must wrap all the text nodes inside of a <Text> component. You cannot have a text node directly under a <View>.

// BAD: will raise exception, can't have a text node as child of a <View>
<View>
Some text
</View>
// 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:

  • (Developer) React components are designed with strong isolation in mind: You should be able to drop a component anywhere in your application, trusting that as long as the props are the same, it will look and behave the same way. Text properties that could inherit from outside of the props would break this isolation.

  • (Implementor) The implementation of React Native is also simplified. We do not need to have a fontFamily field on every single element, and we do not need to potentially traverse the tree up to the root every time we display a text node. The style inheritance is only encoded inside of the native Text component and doesn't leak to other components or the system itself.

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:

  • '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

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:

  • 'phoneNumber'
  • 'link'
  • 'email'
  • 'none'
  • 'all'
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:

  • head - The line is displayed so that the end fits in the container and the missing text at the beginning of the line is indicated by an ellipsis glyph. e.g., "...wxyz"
  • middle - The line is displayed so that the beginning and end fit in the container and the missing text in the middle is indicated by an ellipsis glyph. "ab...yz"
  • tail - The line is displayed so that the beginning fits in the container and the missing text at the end of the line is indicated by an ellipsis glyph. e.g., "abcd..."
  • clip - Lines are not drawn past the edge of the text container.

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:

  • 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

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/index.html b/docs/0.60/textinput/index.html index ea4ffcc330a..0d325255ea4 100644 --- a/docs/0.60/textinput/index.html +++ b/docs/0.60/textinput/index.html @@ -16,7 +16,7 @@ TextInput · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/timepickerandroid/index.html index b487b7a0df6..a0d1161bf23 100644 --- a/docs/0.60/timepickerandroid/index.html +++ b/docs/0.60/timepickerandroid/index.html @@ -16,7 +16,7 @@ TimePickerAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/timers/index.html index ba4ca50ef25..702387bc087 100644 --- a/docs/0.60/timers/index.html +++ b/docs/0.60/timers/index.html @@ -16,7 +16,7 @@ Timers · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/toastandroid/index.html index c4c7d8cf1e6..b61aedfb52a 100644 --- a/docs/0.60/toastandroid/index.html +++ b/docs/0.60/toastandroid/index.html @@ -16,7 +16,7 @@ ToastAndroid · React Native - + @@ -36,7 +36,7 @@
hideToast = () => {
this.setState({
visible: false
});
};
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/index.html b/docs/0.60/toolbarandroid/index.html index 9d753ecde62..1a42baae3f2 100644 --- a/docs/0.60/toolbarandroid/index.html +++ b/docs/0.60/toolbarandroid/index.html @@ -16,7 +16,7 @@ ToolbarAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/touchablehighlight/index.html index eeb85035fc9..bcfa82f9d4e 100644 --- a/docs/0.60/touchablehighlight/index.html +++ b/docs/0.60/touchablehighlight/index.html @@ -16,7 +16,7 @@ TouchableHighlight · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/touchablenativefeedback/index.html index 557e99f3389..40563e2a45f 100644 --- a/docs/0.60/touchablenativefeedback/index.html +++ b/docs/0.60/touchablenativefeedback/index.html @@ -16,7 +16,7 @@ TouchableNativeFeedback · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/touchableopacity/index.html index cfb7884c0c0..b671114da67 100644 --- a/docs/0.60/touchableopacity/index.html +++ b/docs/0.60/touchableopacity/index.html @@ -16,7 +16,7 @@ TouchableOpacity · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/touchablewithoutfeedback/index.html index 1e158ab110a..92979915ab0 100644 --- a/docs/0.60/touchablewithoutfeedback/index.html +++ b/docs/0.60/touchablewithoutfeedback/index.html @@ -16,7 +16,7 @@ TouchableWithoutFeedback · React Native - + @@ -31,7 +31,7 @@
Version: 0.60

TouchableWithoutFeedback

Do not use unless you have a very good reason. All elements that respond to press should have a visual feedback when touched.

TouchableWithoutFeedback supports only one child. If you wish to have several child components, wrap them in a View. Importantly, TouchableWithoutFeedback works by cloning its child and applying responder props to it. It is therefore required that any intermediary components pass through those props to the underlying React Native component.

Usage Example

function MyComponent(props) {
return (
<View {...props} style={{ flex: 1, backgroundColor: '#fff' }}>
<Text>My Component</Text>
</View>
);
}
<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:

  • '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

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/index.html b/docs/0.60/transforms/index.html index 96e7765cba4..fe33a108b71 100644 --- a/docs/0.60/transforms/index.html +++ b/docs/0.60/transforms/index.html @@ -16,7 +16,7 @@ Transforms · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/troubleshooting/index.html index 4de1cf12c6c..af307054715 100644 --- a/docs/0.60/troubleshooting/index.html +++ b/docs/0.60/troubleshooting/index.html @@ -16,7 +16,7 @@ Troubleshooting · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/tutorial/index.html index c1f2e43bd95..00fe9336a1b 100644 --- a/docs/0.60/tutorial/index.html +++ b/docs/0.60/tutorial/index.html @@ -16,7 +16,7 @@ Learn the Basics · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/typescript/index.html index 66a4fbcc25e..5efb21702bb 100644 --- a/docs/0.60/typescript/index.html +++ b/docs/0.60/typescript/index.html @@ -16,7 +16,7 @@ Using TypeScript with React Native · React Native - + @@ -37,7 +37,7 @@
<View style={styles.button}>
<Button
title="+"
onPress={onIncrement}
accessibilityLabel="increment"
color="blue"
/>
</View>
</View>
</View>
);
}
}
// 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/index.html b/docs/0.60/upgrading/index.html index 54959671dee..166b976f84d 100644 --- a/docs/0.60/upgrading/index.html +++ b/docs/0.60/upgrading/index.html @@ -16,7 +16,7 @@ Upgrading to new React Native versions · React Native - + @@ -30,7 +30,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/usecolorscheme/index.html b/docs/0.60/usecolorscheme/index.html index 5b697db5e61..e67f4c85613 100644 --- a/docs/0.60/usecolorscheme/index.html +++ b/docs/0.60/usecolorscheme/index.html @@ -16,7 +16,7 @@ useColorScheme · React Native - + @@ -31,7 +31,7 @@
Version: 0.60

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.
import { Text, useColorScheme } from 'react-native';
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.60/usewindowdimensions/index.html b/docs/0.60/usewindowdimensions/index.html index c9348c9ecb8..4cd65fa079b 100644 --- a/docs/0.60/usewindowdimensions/index.html +++ b/docs/0.60/usewindowdimensions/index.html @@ -16,7 +16,7 @@ useWindowDimensions · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/using-a-listview/index.html index 70c6a9ba2f4..89856d2f965 100644 --- a/docs/0.60/using-a-listview/index.html +++ b/docs/0.60/using-a-listview/index.html @@ -16,7 +16,7 @@ Using List Views · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/using-a-scrollview/index.html index 0f1d83b6240..9224f29d4f3 100644 --- a/docs/0.60/using-a-scrollview/index.html +++ b/docs/0.60/using-a-scrollview/index.html @@ -16,7 +16,7 @@ Using a ScrollView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/vibration/index.html index 5f9ebd20d22..86b3ee09068 100644 --- a/docs/0.60/vibration/index.html +++ b/docs/0.60/vibration/index.html @@ -16,7 +16,7 @@ Vibration · React Native - + @@ -34,7 +34,7 @@
Vibration.vibrate(PATTERN, true);
// Android: wait 1s -> vibrate 2s -> wait 3s -> wait 1s -> vibrate 2s -> wait 3s -> ...
// iOS: wait 1s -> vibrate -> wait 2s -> vibrate -> wait 3s -> vibrate -> wait 1s -> vibrate -> wait 2s -> vibrate -> wait 3s -> vibrate -> ...
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/index.html b/docs/0.60/vibrationios/index.html index fe7a74670bb..fc042472fe1 100644 --- a/docs/0.60/vibrationios/index.html +++ b/docs/0.60/vibrationios/index.html @@ -16,7 +16,7 @@ VibrationIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/view-style-props/index.html index ce8f034b7d7..2ccfd19b59a 100644 --- a/docs/0.60/view-style-props/index.html +++ b/docs/0.60/view-style-props/index.html @@ -16,7 +16,7 @@ View Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/view/index.html index 1b936acf69e..4ea19bc8335 100644 --- a/docs/0.60/view/index.html +++ b/docs/0.60/view/index.html @@ -16,7 +16,7 @@ View · React Native - + @@ -30,7 +30,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/index.html b/docs/0.60/viewpagerandroid/index.html index 27485ca27dc..5e2e709388d 100644 --- a/docs/0.60/viewpagerandroid/index.html +++ b/docs/0.60/viewpagerandroid/index.html @@ -16,7 +16,7 @@ ViewPagerAndroid · React Native - + @@ -32,7 +32,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.

  • '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

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:

  • position - index of first page from the left that is currently visible
  • offset - value from range [0, 1] describing stage between page transitions. Value x means that (1 - x) fraction of the page at "position" index is visible, and x fraction of the next page is visible.
TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

  • idle, meaning there is no interaction with the page scroller happening at the time
  • dragging, meaning there is currently an interaction with the page scroller
  • settling, meaning that there was an interaction with the page scroller, and the page scroller is now finishing its closing or opening animation
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:

  • position - index of page that has been selected
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.

  • position - index of page that will be selected
TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

  • position - index of page that will be selected
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/index.html b/docs/0.60/virtualizedlist/index.html index 369d206b8ff..4cb6517d513 100644 --- a/docs/0.60/virtualizedlist/index.html +++ b/docs/0.60/virtualizedlist/index.html @@ -16,7 +16,7 @@ VirtualizedList · React Native - + @@ -30,7 +30,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 Class, a render function, or a rendered element.

TypeRequired
component, function, 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 Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListFooterComponentStyle

Styling for internal View for ListFooterComponent

TypeRequired
ViewStylePropNo

ListHeaderComponent

Rendered at the top of all the items. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, 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 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/index.html b/docs/0.60/webview/index.html index a38f7eb4c0a..88a3a3156bd 100644 --- a/docs/0.60/webview/index.html +++ b/docs/0.60/webview/index.html @@ -16,7 +16,7 @@ 🚧 WebView · React Native - + @@ -32,7 +32,7 @@
class MyWeb extends Component {
render() {
return (
<WebView
source={{
uri: 'https://github.com/facebook/react-native'
}}
style={{ marginTop: 20 }}
/>
);
}
}

Minimal example with inline HTML:

import React, { Component } from 'react';
import { WebView } from 'react-native';
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

  • uri (string) - The URI to load in the WebView. Can be a local or remote file.
  • method (string) - The HTTP Method to use. Defaults to GET if not specified. On Android, the only supported methods are GET and POST.
  • headers (object) - Additional HTTP headers to send with the request. On Android, this can only be used with GET requests.
  • body (string) - The 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. On Android, this can only be used with POST requests.

Static HTML

  • html (string) - A static HTML page to display in the WebView.
  • baseUrl (string) - The base URL to be used for any relative links in the 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:

  • component (any)
  • props (object)
  • viewManager (object)
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:

  • normal: 0.998
  • fast: 0.99 (the default for iOS web view)
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:

  • never (default) - WebView will not allow a secure origin to load content from an insecure origin.
  • always - WebView will allow a secure origin to load content from any other origin, even if that origin is insecure.
  • compatibility - WebView will attempt to be compatible with the approach of a modern web browser with regard to mixed content.
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:

  • phoneNumber
  • link
  • address
  • calendarEvent
  • none
  • all

With the new WebKit implementation, we have three new values:

  • trackingNumber
  • flightNumber
  • lookupSuggestion
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/index.html b/docs/0.61/_getting-started-linux-android/index.html index a214a9634b8..8884b60471b 100644 --- a/docs/0.61/_getting-started-linux-android/index.html +++ b/docs/0.61/_getting-started-linux-android/index.html @@ -16,7 +16,7 @@ _getting-started-linux-android · React Native - + @@ -31,7 +31,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 intallation 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/index.html b/docs/0.61/_getting-started-macos-android/index.html index b60e2aac8b9..ed8583d0c8d 100644 --- a/docs/0.61/_getting-started-macos-android/index.html +++ b/docs/0.61/_getting-started-macos-android/index.html @@ -16,7 +16,7 @@ _getting-started-macos-android · React Native - + @@ -31,7 +31,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 cask install 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 intallation 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/index.html b/docs/0.61/_getting-started-macos-ios/index.html index ef6ed0abe43..9420a1ca03d 100644 --- a/docs/0.61/_getting-started-macos-ios/index.html +++ b/docs/0.61/_getting-started-macos-ios/index.html @@ -16,7 +16,7 @@ _getting-started-macos-ios · React Native - + @@ -31,7 +31,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/index.html b/docs/0.61/_getting-started-windows-android/index.html index 6b8f5364d3d..9e20cfe181b 100644 --- a/docs/0.61/_getting-started-windows-android/index.html +++ b/docs/0.61/_getting-started-windows-android/index.html @@ -16,7 +16,7 @@ _getting-started-windows-android · React Native - + @@ -30,7 +30,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 intallation 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/index.html b/docs/0.61/_integration-with-exisiting-apps-java/index.html index c858740868b..025551a7ff8 100644 --- a/docs/0.61/_integration-with-exisiting-apps-java/index.html +++ b/docs/0.61/_integration-with-exisiting-apps-java/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-java · React Native - + @@ -45,7 +45,7 @@
@Override
protected void onDestroy() {
super.onDestroy();
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/index.html b/docs/0.61/_integration-with-exisiting-apps-objc/index.html index 2c0374cb6c5..bd37825ab75 100644 --- a/docs/0.61/_integration-with-exisiting-apps-objc/index.html +++ b/docs/0.61/_integration-with-exisiting-apps-objc/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-objc · React Native - + @@ -39,7 +39,7 @@
// Module name
AppRegistry.registerComponent('RNHighScores', () => RNHighScores);

RNHighScores is the name of your module that will be used when you add a view to React Native from within your iOS application.

The Magic: RCTRootView

Now that your React Native component is created via index.js, you need to add that component to a new or existing ViewController. The easiest path to take is to optionally create an event path to your component and then add that component to an existing ViewController.

We will tie our React Native component with a new native view in the ViewController that will actually contain it called RCTRootView .

1. Create an Event Path

You can add a new link on the main game menu to go to the "High Score" React Native page.

Event Path

2. Event Handler

We will now add an event handler from the menu link. A method will be added to the main ViewController of your application. This is where RCTRootView comes into play.

When you build a React Native application, you use the Metro bundler to create an index.bundle that will be served by the React Native server. Inside index.bundle will be our RNHighScore module. So, we need to point our RCTRootView to the location of the index.bundle resource (via NSURL) and tie it to the module.

We will, for debugging purposes, log that the event handler was invoked. Then, we will create a string with the location of our React Native code that exists inside the index.bundle. Finally, we will create the main RCTRootView. Notice how we provide RNHighScores as the moduleName that we created above when writing the code for our React Native component.

First import the RCTRootView header.

#import <React/RCTRootView.h>

The initialProperties are here for illustration purposes so we have some data for our high score screen. In our React Native component, we will use this.props to get access to that data.

- (IBAction)highScoreButtonPressed:(id)sender {
NSLog(@"High Score Button Pressed");
NSURL *jsCodeLocation = [NSURL URLWithString:@"http://localhost:8081/index.bundle?platform=ios"];
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/index.html b/docs/0.61/_integration-with-exisiting-apps-swift/index.html index 53446a1c82e..61057f8d205 100644 --- a/docs/0.61/_integration-with-exisiting-apps-swift/index.html +++ b/docs/0.61/_integration-with-exisiting-apps-swift/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-swift · React Native - + @@ -40,7 +40,7 @@
// Module name
AppRegistry.registerComponent('RNHighScores', () => RNHighScores);

RNHighScores is the name of your module that will be used when you add a view to React Native from within your iOS application.

The Magic: RCTRootView

Now that your React Native component is created via index.js, you need to add that component to a new or existing ViewController. The easiest path to take is to optionally create an event path to your component and then add that component to an existing ViewController.

We will tie our React Native component with a new native view in the ViewController that will actually contain it called RCTRootView .

1. Create an Event Path

You can add a new link on the main game menu to go to the "High Score" React Native page.

Event Path

2. Event Handler

We will now add an event handler from the menu link. A method will be added to the main ViewController of your application. This is where RCTRootView comes into play.

When you build a React Native application, you use the Metro bundler to create an index.bundle that will be served by the React Native server. Inside index.bundle will be our RNHighScore module. So, we need to point our RCTRootView to the location of the index.bundle resource (via NSURL) and tie it to the module.

We will, for debugging purposes, log that the event handler was invoked. Then, we will create a string with the location of our React Native code that exists inside the index.bundle. Finally, we will create the main RCTRootView. Notice how we provide RNHighScores as the moduleName that we created above when writing the code for our React Native component.

First import the React library.

import React

The initialProperties are here for illustration purposes so we have some data for our high score screen. In our React Native component, we will use this.props to get access to that data.

@IBAction func highScoreButtonTapped(sender : UIButton) {
NSLog("Hello")
let jsCodeLocation = URL(string: "http://localhost:8081/index.bundle?platform=ios")
let mockData:NSDictionary = ["scores":
[
["name":"Alex", "value":"42"],
["name":"Joel", "value":"10"]
]
]
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/index.html b/docs/0.61/accessibility/index.html index 42db43402ad..e59ce097a46 100644 --- a/docs/0.61/accessibility/index.html +++ b/docs/0.61/accessibility/index.html @@ -16,7 +16,7 @@ Accessibility · React Native - + @@ -32,7 +32,7 @@
if (Platform.OS === 'android') {
UIManager.sendAccessibilityEvent(
findNodeHandle(this),
UIManager.AccessibilityEventTypes.typeViewFocused
);
}

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.

Testing TalkBack Support (Android)

To enable TalkBack, go to the Settings app on your Android device or emulator. Tap Accessibility, then TalkBack. Toggle the "Use service" switch to enable or disable it.

P.S. Android emulator doesn’t have TalkBack by default. To install it:

  1. Download TalkBack file here: https://google-talkback.en.uptodown.com/android
  2. Drag the downloaded .apk file into the emulator

You can use the volume key shortcut to toggle TalkBack. To turn on the volume key shortcut, go to the Settings app, then Accessibility. At the top, turn on Volume key shortcut.

To use the volume key shortcut, press both volume keys for 3 seconds to start an accessibility tool.

Additionally, if you prefer, you can toggle TalkBack via command line with:

# disable
adb shell settings put secure enabled_accessibility_services com.android.talkback/com.google.android.marvin.talkback.TalkBackService
# 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/index.html b/docs/0.61/accessibilityinfo/index.html index 194829e60de..31bc1c14052 100644 --- a/docs/0.61/accessibilityinfo/index.html +++ b/docs/0.61/accessibilityinfo/index.html @@ -16,7 +16,7 @@ AccessibilityInfo · React Native - + @@ -37,7 +37,7 @@
_handleScreenReaderToggled = (screenReaderEnabled) => {
this.setState({ screenReaderEnabled });
};
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:

  • 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 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/index.html b/docs/0.61/actionsheetios/index.html index ba43d4db631..a249de98ecc 100644 --- a/docs/0.61/actionsheetios/index.html +++ b/docs/0.61/actionsheetios/index.html @@ -16,7 +16,7 @@ ActionSheetIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/activityindicator/index.html index a246c822671..916dc6e6ef2 100644 --- a/docs/0.61/activityindicator/index.html +++ b/docs/0.61/activityindicator/index.html @@ -16,7 +16,7 @@ ActivityIndicator · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/alert/index.html index f7f00f3a3a0..8c0adf8ceb2 100644 --- a/docs/0.61/alert/index.html +++ b/docs/0.61/alert/index.html @@ -16,7 +16,7 @@ Alert · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/alertios/index.html index 630fe1d0ffb..9b8fdd6f2f8 100644 --- a/docs/0.61/alertios/index.html +++ b/docs/0.61/alertios/index.html @@ -16,7 +16,7 @@ 🚧 AlertIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/animated/index.html index 7cecc569e10..53ef2040c0e 100644 --- a/docs/0.61/animated/index.html +++ b/docs/0.61/animated/index.html @@ -16,7 +16,7 @@ Animated · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/animatedvalue/index.html index 8b4a0000a8b..5d0a399058e 100644 --- a/docs/0.61/animatedvalue/index.html +++ b/docs/0.61/animatedvalue/index.html @@ -16,7 +16,7 @@ AnimatedValue · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/animatedvaluexy/index.html index 574ecc1a973..9e031a0be2c 100644 --- a/docs/0.61/animatedvaluexy/index.html +++ b/docs/0.61/animatedvaluexy/index.html @@ -16,7 +16,7 @@ AnimatedValueXY · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/animations/index.html index d9905b9acd3..a686b7ac015 100644 --- a/docs/0.61/animations/index.html +++ b/docs/0.61/animations/index.html @@ -16,7 +16,7 @@ Animations · React Native - + @@ -31,7 +31,7 @@
Version: 0.61

Animations

Animations are very important to create a great user experience. Stationary objects must overcome inertia as they start moving. Objects in motion have momentum and rarely come to a stop immediately. Animations allow you to convey physically believable motion in your interface.

React Native provides two complementary animation systems: Animated for granular and interactive control of specific values, and LayoutAnimation for animated global layout transactions.

Animated API

The Animated API is designed to concisely express a wide variety of interesting animation and interaction patterns in a very performant way. Animated focuses on declarative relationships between inputs and outputs, with configurable transforms in between, and start/stop methods to control time-based animation execution.

Animated exports six animatable component types: View, Text, Image, ScrollView, FlatList and SectionList, but you can also create your own using Animated.createAnimatedComponent().

For example, a container view that fades in when it is mounted may look like this:

Let's break down what's happening here. In the FadeInView constructor, a new Animated.Value called fadeAnim is initialized as part of state. The opacity property on the View is mapped to this animated value. Behind the scenes, the numeric value is extracted and used to set opacity.

When the component mounts, the opacity is set to 0. Then, an easing animation is started on the fadeAnim animated value, which will update all of its dependent mappings (in this case, only the opacity) on each frame as the value animates to the final value of 1.

This is done in an optimized way that is faster than calling setState and re-rendering. Because the entire configuration is declarative, we will be able to implement further optimizations that serialize the configuration and runs the animation on a high-priority thread.

Configuring animations

Animations are heavily configurable. Custom and predefined easing functions, delays, durations, decay factors, spring constants, and more can all be tweaked depending on the type of animation.

Animated provides several animation types, the most commonly used one being Animated.timing(). It supports animating a value over time using one of various predefined easing functions, or you can use your own. Easing functions are typically used in animation to convey gradual acceleration and deceleration of objects.

By default, timing will use a easeInOut curve that conveys gradual acceleration to full speed and concludes by gradually decelerating to a stop. You can specify a different easing function by passing a easing parameter. Custom duration or even a delay before the animation starts is also supported.

For example, if we want to create a 2-second long animation of an object that slightly backs up before moving to its final position:

Animated.timing(this.state.xPosition, {
toValue: 100,
easing: Easing.back(),
duration: 2000
}).start();

Take a look at the Configuring animations section of the Animated API reference to learn more about all the config parameters supported by the built-in animations.

Composing animations

Animations can be combined and played in sequence or in parallel. Sequential animations can play immediately after the previous animation has finished, or they can start after a specified delay. The Animated API provides several methods, such as sequence() and delay(), each of which take an array of animations to execute and automatically calls start()/stop() as needed.

For example, the following animation coasts to a stop, then it springs back while twirling in parallel:

Animated.sequence([
// decay, then spring to start and twirl
Animated.decay(position, {
// coast to a stop
velocity: { x: gestureState.vx, y: gestureState.vy }, // velocity from gesture release
deceleration: 0.997
}),
Animated.parallel([
// after decay, in parallel:
Animated.spring(position, {
toValue: { x: 0, y: 0 } // return to start
}),
Animated.timing(twirl, {
// and twirl
toValue: 360
})
])
]).start(); // start the sequence group

If one animation is stopped or interrupted, then all other animations in the group are also stopped. Animated.parallel has a stopTogether option that can be set to false to disable this.

You can find a full list of composition methods in the Composing animations section of the Animated API reference.

Combining animated values

You can combine two animated values via addition, multiplication, division, or modulo to make a new animated value.

There are some cases where an animated value needs to invert another animated value for calculation. An example is inverting a scale (2x --> 0.5x):

const a = new Animated.Value(1);
const b = Animated.divide(1, a);
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:

  • spring.stopAnimation(callback) will stop the animation and invoke callback with the final value. This is useful when making gesture transitions.
  • spring.addListener(callback) will invoke callback asynchronously while the animation is running, providing a recent value. This is useful for triggering state changes, for example snapping a bobble to a new option as the user drags it closer, because these larger state changes are less sensitive to a few frames of lag compared to continuous gestures like panning which need to run at 60 fps.

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/index.html b/docs/0.61/app-extensions/index.html index e9a80f7c988..d03f5396b50 100644 --- a/docs/0.61/app-extensions/index.html +++ b/docs/0.61/app-extensions/index.html @@ -16,7 +16,7 @@ App Extensions · React Native - + @@ -30,7 +30,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/appearance/index.html b/docs/0.61/appearance/index.html index 6857c504f3b..4ca82c96761 100644 --- a/docs/0.61/appearance/index.html +++ b/docs/0.61/appearance/index.html @@ -16,7 +16,7 @@ Appearance · React Native - + @@ -30,7 +30,7 @@
Version: 0.61

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.61/appregistry/index.html b/docs/0.61/appregistry/index.html index 45fa235c9ba..f378d267e2d 100644 --- a/docs/0.61/appregistry/index.html +++ b/docs/0.61/appregistry/index.html @@ -16,7 +16,7 @@ AppRegistry · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/appstate/index.html index a0d54250765..7221493664a 100644 --- a/docs/0.61/appstate/index.html +++ b/docs/0.61/appstate/index.html @@ -16,7 +16,7 @@ AppState · React Native - + @@ -35,7 +35,7 @@
_handleAppStateChange = (nextAppState) => {
if (
this.state.appState.match(/inactive|background/) &&
nextAppState === 'active'
) {
console.log('App has come to the foreground!');
}
this.setState({ appState: nextAppState });
};
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/index.html b/docs/0.61/asyncstorage/index.html index 07b5cf1541d..914ed7ed0b5 100644 --- a/docs/0.61/asyncstorage/index.html +++ b/docs/0.61/asyncstorage/index.html @@ -16,7 +16,7 @@ 🚧 AsyncStorage · React Native - + @@ -38,7 +38,7 @@
AsyncStorage.multiSet(multi_set_pairs, (err) => {
AsyncStorage.multiMerge(multi_merge_pairs, (err) => {
AsyncStorage.multiGet(['UID234', 'UID345'], (err, stores) => {
stores.map((result, i, store) => {
let key = store[i][0];
let val = store[i][1];
console.log(key, val);
});
});
});
});
// 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/index.html b/docs/0.61/backandroid/index.html index 28927eaa096..9326e5cbe72 100644 --- a/docs/0.61/backandroid/index.html +++ b/docs/0.61/backandroid/index.html @@ -16,7 +16,7 @@ BackAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/backhandler/index.html index b7b96df5017..a56e87fcf20 100644 --- a/docs/0.61/backhandler/index.html +++ b/docs/0.61/backhandler/index.html @@ -16,7 +16,7 @@ BackHandler · React Native - + @@ -34,7 +34,7 @@
handleBackPress = () => {
this.goBack(); // works best when the goBack is async
return true;
}

Lifecycle alternative:

componentDidMount() {
this.backHandler = BackHandler.addEventListener('hardwareBackPress', () => {
this.goBack(); // works best when the goBack is async
return true;
});
}
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/index.html b/docs/0.61/building-for-tv/index.html index 6bb53a0a002..6ac56a1db78 100644 --- a/docs/0.61/building-for-tv/index.html +++ b/docs/0.61/building-for-tv/index.html @@ -16,7 +16,7 @@ Building For TV Devices · React Native - + @@ -35,7 +35,7 @@
componentDidMount() {
this._enableTVEventHandler();
}
componentWillUnmount() {
this._disableTVEventHandler();
}
}

  • Dev Menu support: On the simulator, cmd-M will bring up the developer menu, similar to Android. To bring it up on a real Android TV device, press the menu button or long press the fast-forward button on the remote. (Please do not shake the Android TV device, that will not work :) )

  • Known issues:

    • InputText components do not work for now (i.e. they cannot receive focus).
Edit this page
Last updated on
- + diff --git a/docs/0.61/button/index.html b/docs/0.61/button/index.html index b35952303c2..a0a3278ad9a 100644 --- a/docs/0.61/button/index.html +++ b/docs/0.61/button/index.html @@ -16,7 +16,7 @@ Button · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/cameraroll/index.html index 7fe1a706519..cc0822e856f 100644 --- a/docs/0.61/cameraroll/index.html +++ b/docs/0.61/cameraroll/index.html @@ -16,7 +16,7 @@ 🚧 CameraRoll · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/checkbox/index.html index b0b02d10080..6f809f04181 100644 --- a/docs/0.61/checkbox/index.html +++ b/docs/0.61/checkbox/index.html @@ -16,7 +16,7 @@ 🚧 CheckBox · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/clipboard/index.html index 8332f9e91c6..1b892c5d8a4 100644 --- a/docs/0.61/clipboard/index.html +++ b/docs/0.61/clipboard/index.html @@ -16,7 +16,7 @@ 🚧 Clipboard · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/colors/index.html index 7b00aedb789..971c8f22aa1 100644 --- a/docs/0.61/colors/index.html +++ b/docs/0.61/colors/index.html @@ -16,7 +16,7 @@ Color Reference · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/communication-android/index.html index 8c4df8232c4..6705f3c2e66 100644 --- a/docs/0.61/communication-android/index.html +++ b/docs/0.61/communication-android/index.html @@ -16,7 +16,7 @@ Communication between native and React Native · React Native - + @@ -32,7 +32,7 @@
export default class ImageBrowserApp extends React.Component {
renderImage(imgURI) {
return <Image source={{ uri: imgURI }} />;
}
render() {
return <View>{this.props.images.map(this.renderImage)}</View>;
}
}

ReactRootView provides a read-write property appProperties. After appProperties is set, the React Native app is re-rendered with new properties. The update is only performed when the new updated properties differ from the previous ones.

Bundle updatedProps = mReactRootView.getAppProperties();
ArrayList<String> imageList = new ArrayList<String>(Arrays.asList(
"http://foo.com/bar3.png",
"http://foo.com/bar4.png"
));
updatedProps.putStringArrayList("images", imageList);
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:

  • As events can be sent from anywhere, they can introduce spaghetti-style dependencies into your project.
  • Events share namespace, which means that you may encounter some name collisions. Collisions will not be detected statically, which makes them hard to debug.
  • If you use several instances of the same React Native component and you want to distinguish them from the perspective of your event, you'll likely need to introduce identifiers and pass them along with events (you can use the native view's reactTag as an identifier).

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/index.html b/docs/0.61/communication-ios/index.html index de86f1c1b4c..349528616bd 100644 --- a/docs/0.61/communication-ios/index.html +++ b/docs/0.61/communication-ios/index.html @@ -16,7 +16,7 @@ Communication between native and React Native · React Native - + @@ -41,7 +41,7 @@
#pragma mark - RCTRootViewDelegate
- (void)rootViewDidChangeIntrinsicSize:(RCTRootView *)rootView
{
CGRect newFrame = rootView.frame;
newFrame.size = rootView.intrinsicContentSize;
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/index.html b/docs/0.61/components-and-apis/index.html index c354cd6f8d6..595db45228e 100644 --- a/docs/0.61/components-and-apis/index.html +++ b/docs/0.61/components-and-apis/index.html @@ -16,7 +16,7 @@ Components and APIs · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/custom-webview-android/index.html index ff79f0a5c8e..0183bc0540f 100644 --- a/docs/0.61/custom-webview-android/index.html +++ b/docs/0.61/custom-webview-android/index.html @@ -16,7 +16,7 @@ Custom WebView · React Native - + @@ -57,7 +57,7 @@
_onNavigationCompleted = (event) => {
const { onNavigationCompleted } = this.props;
onNavigationCompleted && onNavigationCompleted(event);
};
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/index.html b/docs/0.61/custom-webview-ios/index.html index 710f94b525c..e4bd93ad11e 100644 --- a/docs/0.61/custom-webview-ios/index.html +++ b/docs/0.61/custom-webview-ios/index.html @@ -16,7 +16,7 @@ Custom WebView · React Native - + @@ -60,7 +60,7 @@
_onNavigationCompleted = (event) => {
const { onNavigationCompleted } = this.props;
onNavigationCompleted && onNavigationCompleted(event);
};
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/index.html b/docs/0.61/datepickerandroid/index.html index e6ebe47c764..ff8c0a85a95 100644 --- a/docs/0.61/datepickerandroid/index.html +++ b/docs/0.61/datepickerandroid/index.html @@ -16,7 +16,7 @@ 🚧 DatePickerAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/datepickerios/index.html index 7e7b042ea94..45446550f4a 100644 --- a/docs/0.61/datepickerios/index.html +++ b/docs/0.61/datepickerios/index.html @@ -16,7 +16,7 @@ 🚧 DatePickerIOS · React Native - + @@ -35,7 +35,7 @@
render() {
return (
<View style={styles.container}>
<DatePickerIOS
date={this.state.chosenDate}
onDateChange={this.setDate}
/>
</View>
);
}
}
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/index.html b/docs/0.61/debugging/index.html index 70db12de598..25a49c6a159 100644 --- a/docs/0.61/debugging/index.html +++ b/docs/0.61/debugging/index.html @@ -16,7 +16,7 @@ Debugging · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/devsettings/index.html index 8ca98219570..fe7181c8435 100644 --- a/docs/0.61/devsettings/index.html +++ b/docs/0.61/devsettings/index.html @@ -16,7 +16,7 @@ DevSettings · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/dimensions/index.html index 303a0dbf58d..120fd546748 100644 --- a/docs/0.61/dimensions/index.html +++ b/docs/0.61/dimensions/index.html @@ -16,7 +16,7 @@ Dimensions · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/direct-manipulation/index.html index 04698f47487..7d6b089fc71 100644 --- a/docs/0.61/direct-manipulation/index.html +++ b/docs/0.61/direct-manipulation/index.html @@ -16,7 +16,7 @@ Direct Manipulation · React Native - + @@ -31,7 +31,7 @@
Version: 0.61

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:

setOpacityTo(value) {
// Redacted: animation related code
this.refs[CHILD_REF].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={this._handlePress}>
<View style={styles.button}>
<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:

constructor(props) {
super(props);
this.state = { myButtonOpacity: 1, };
}
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:

  • x
  • y
  • width
  • height
  • pageX
  • pageY

Note that these measurements are not available until after the rendering has been completed in native. If you need the measurements as soon as possible, consider using the onLayout prop instead.

measureInWindow(callback)

Determines the location of the given view in the window and returns the values via an async callback. If the React root view is embedded in another native view, this will give you the absolute coordinates. If successful, the callback will be called with the following arguments:

  • x
  • y
  • width
  • height

measureLayout(relativeToNativeNode, onSuccess, onFail)

Like measure(), but measures the view relative 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/index.html b/docs/0.61/drawerlayoutandroid/index.html index f4e554ea897..08413d73a2e 100644 --- a/docs/0.61/drawerlayoutandroid/index.html +++ b/docs/0.61/drawerlayoutandroid/index.html @@ -16,7 +16,7 @@ DrawerLayoutAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/easing/index.html index ccdd1fb29a8..9154aaa20b9 100644 --- a/docs/0.61/easing/index.html +++ b/docs/0.61/easing/index.html @@ -16,7 +16,7 @@ Easing · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/enviroment-setup/index.html index fe911728992..a48421bdf85 100644 --- a/docs/0.61/enviroment-setup/index.html +++ b/docs/0.61/enviroment-setup/index.html @@ -16,7 +16,7 @@ Getting Started · React Native - + @@ -32,7 +32,7 @@
Version: 0.61

Getting Started

This page will help you install and build your first React Native app.

If you are new to mobile development, the easiest way to get started is with Expo CLI. Expo is a set of tools built around React Native and, while it has many features, the most relevant feature for us right now is that it can get you writing a React Native app within minutes. You will only need a recent version of Node.js and a phone or emulator. If you'd like to try out React Native directly in your web browser before installing any tools, you can try out Snack.

If you are already familiar with mobile development, you may want to use React Native CLI. It requires Xcode or Android Studio to get started. If you already have one of these tools installed, you should be able to get up and running within a few minutes. If they are not installed, you should expect to spend about an hour installing and configuring them.

Assuming that you have Node 12 LTS or greater installed, you can use npm to install the Expo CLI command line utility:

npm install -g expo-cli

Then run the following commands to create a new React Native project called "AwesomeProject":

expo init AwesomeProject
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/index.html b/docs/0.61/fast-refresh/index.html index 66287f96b24..01fd8d2b9bb 100644 --- a/docs/0.61/fast-refresh/index.html +++ b/docs/0.61/fast-refresh/index.html @@ -16,7 +16,7 @@ Fast Refresh · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/flatlist/index.html index 4655d42e7f2..b8870ac038b 100644 --- a/docs/0.61/flatlist/index.html +++ b/docs/0.61/flatlist/index.html @@ -16,7 +16,7 @@ FlatList · React Native - + @@ -31,7 +31,7 @@
Version: 0.61

FlatList

A performant interface for rendering basic, flat lists, supporting the most handy features:

  • Fully cross-platform.
  • Optional horizontal mode.
  • Configurable viewability callbacks.
  • Header support.
  • Footer support.
  • Separator support.
  • Pull to Refresh.
  • Scroll loading.
  • ScrollToIndex support.
  • Multiple column support.

If you need section support, use <SectionList>.

Basic Example:

To render multiple columns, use the numColumns prop. Using this approach instead of a flexWrap layout can prevent conflicts with the item height logic.

More complex, multi-select example demonstrating `` usage for perf optimization and avoiding bugs.

  • By passing extraData={selected} to FlatList we make sure FlatList itself will re-render when the state changes. Without setting this prop, FlatList would not know it needs to re-render any items because it is a PureComponent and the prop comparison will not show any changes.
  • keyExtractor tells the list to use the ids for the react keys instead of the default key property.

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, unless it is nested in another FlatList of same orientation.

renderItem

renderItem({ item, index, separators });

Takes an item from data and renders it into the list.

Provides additional metadata like index if you need it, as well as a more generic separators.updateProps function which let you set whatever props you want to change the rendering of either the leading separator or trailing separator in case the more common highlight and unhighlight (which set the highlighted: boolean prop) are insufficient for your use case.

TypeRequired
functionYes
  • item (Object): The item from data being rendered.
  • index (number): The index corresponding to this item in the data array.
  • separators (Object)
    • highlight (Function)
    • unhighlight (Function)
    • updateProps (Function)
      • select (enum('leading', 'trailing'))
      • newProps (Object)

Example usage:

<FlatList
ItemSeparatorComponent={Platform.OS !== 'android' && ({highlighted}) => (
<View style={[style.separator, highlighted && {marginLeft: 0}]} />
)}
data={[{title: 'Title Text', key: 'item1'}]}
renderItem={({item, index, separators}) => (
<TouchableHighlight
onPress={() => this._onPress(item)}
onShowUnderlay={separators.highlight}
onHideUnderlay={separators.unhighlight}>
<View style={{backgroundColor: 'white'}}>
<Text>{item.title}</Text>
</View>
</TouchableHighlight>
)}
/>

data

For simplicity, data is a plain array. If you want to use something else, like an immutable list, use the underlying VirtualizedList directly.

TypeRequired
arrayYes

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted and leadingItem 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
componentNo

ListEmptyComponent

Rendered when the list is empty. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListFooterComponent

Rendered at the bottom of all the items. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListFooterComponentStyle

Styling for internal View for ListFooterComponent

TypeRequired
style objectNo

ListHeaderComponent

Rendered at the top of all the items. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListHeaderComponentStyle

Styling for internal View for ListHeaderComponent

TypeRequired
style objectNo

columnWrapperStyle

Optional custom style for multi-item rows generated when numColumns > 1.

TypeRequired
style objectNo

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, index) => {length: number, offset: number, index: number}

getItemLayout is an optional optimization that allows skipping the measurement of dynamic content if you know the size (height or width) of items ahead of time. getItemLayout is efficient if you have fixed size items, for example:

getItemLayout={(data, index) => (
{length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index}
)}

Adding getItemLayout can be a great performance boost for lists of several hundred items. Remember to include separator length (height or width) in your offset calculation if you specify ItemSeparatorComponent.

TypeRequired
functionNo

horizontal

If true, renders items next to each other horizontally instead of stacked vertically.

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

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

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 falls back to using the index, like React does.

TypeRequired
functionNo

numColumns

Multiple columns can only be rendered with horizontal={false} and will zig-zag like a flexWrap layout. Items should all be the same height - masonry layouts are not supported.

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

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

onViewableItemsChanged

(info: {
viewableItems: array,
changed: array,
}) => void

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

progressViewOffset

Set this when offset is needed for the loading indicator to show correctly.

TypeRequiredPlatform
numberNoAndroid

legacyImplementation

May not have full feature parity and is meant for debugging and performance comparison.

TypeRequired
booleanNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
booleanNo

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

viewabilityConfig

See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
ViewabilityConfigNo

viewabilityConfig takes a type ViewabilityConfig an object with following properties

PropertyRequiredType
minimumViewTimeNonumber
viewAreaCoveragePercentThresholdNonumber
itemVisiblePercentThresholdNonumber
waitForInteractionNoboolean

At least one of the viewAreaCoveragePercentThreshold or itemVisiblePercentThreshold is required. This needs to be done in the constructor to avoid following error (ref):

Error: Changing viewabilityConfig on the fly is not supported`
constructor (props) {
super(props)
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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.

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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'index' (number) - The index to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position.
  • '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.

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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'item' (object) - The item to scroll to. Required.
  • 'viewPosition' (number)

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'offset' (number) - The offset to scroll to. In case of horizontal being true, the offset is the x-value, in any other case the offset is the y-value. Required.
  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.

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/index.html b/docs/0.61/flexbox/index.html index 13c6c5ff6ce..dee9e9ad600 100644 --- a/docs/0.61/flexbox/index.html +++ b/docs/0.61/flexbox/index.html @@ -16,7 +16,7 @@ Layout with Flexbox · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/geolocation/index.html index 1e431dae2c1..8c8a89d0520 100644 --- a/docs/0.61/geolocation/index.html +++ b/docs/0.61/geolocation/index.html @@ -16,7 +16,7 @@ 🚧 Geolocation · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/gesture-responder-system/index.html index 0993e6c9ae6..6507e673a40 100644 --- a/docs/0.61/gesture-responder-system/index.html +++ b/docs/0.61/gesture-responder-system/index.html @@ -16,7 +16,7 @@ Gesture Responder System · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/getting-started/index.html index f6eefd1ddfd..778d01fc5de 100644 --- a/docs/0.61/getting-started/index.html +++ b/docs/0.61/getting-started/index.html @@ -16,7 +16,7 @@ Introduction · React Native - + @@ -30,7 +30,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.58., 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/index.html b/docs/0.61/handling-text-input/index.html index 6cbb13766fa..ad01000012d 100644 --- a/docs/0.61/handling-text-input/index.html +++ b/docs/0.61/handling-text-input/index.html @@ -16,7 +16,7 @@ Handling Text Input · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/handling-touches/index.html index e88c056fd5c..80573863dd7 100644 --- a/docs/0.61/handling-touches/index.html +++ b/docs/0.61/handling-touches/index.html @@ -16,7 +16,7 @@ Handling Touches · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/headless-js-android/index.html index dd590437116..3437128db45 100644 --- a/docs/0.61/headless-js-android/index.html +++ b/docs/0.61/headless-js-android/index.html @@ -16,7 +16,7 @@ Headless JS · React Native - + @@ -40,7 +40,7 @@
}
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 4d801e2e496..b68e068892e 100644 --- a/docs/0.61/height-and-width/index.html +++ b/docs/0.61/height-and-width/index.html @@ -16,7 +16,7 @@ Height and Width · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/hermes/index.html index 6952122fd2f..13e5eb66ffb 100644 --- a/docs/0.61/hermes/index.html +++ b/docs/0.61/hermes/index.html @@ -16,7 +16,7 @@ Using Hermes · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/image-style-props/index.html index aea07b67437..c94937df492 100644 --- a/docs/0.61/image-style-props/index.html +++ b/docs/0.61/image-style-props/index.html @@ -16,7 +16,7 @@ Image Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/image/index.html index 8ae4bb8b2d5..877a1ee2451 100644 --- a/docs/0.61/image/index.html +++ b/docs/0.61/image/index.html @@ -16,7 +16,7 @@ Image · React Native - + @@ -33,7 +33,7 @@
// For WebP support, including animated WebP
implementation 'com.facebook.fresco:animated-webp:2.1.0'
implementation 'com.facebook.fresco:webpsupport:2.0.0'
// 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

  • Layout Props...

  • Shadow Props...

  • Transforms...

  • borderTopRightRadius: number

  • backfaceVisibility: enum('visible', 'hidden')

  • borderBottomLeftRadius: number

  • borderBottomRightRadius: number

  • borderColor: color

  • borderRadius: number

  • borderTopLeftRadius: number

  • backgroundColor: color

  • borderWidth: number

  • opacity: number

  • overflow: enum('visible', 'hidden')

  • resizeMode: Object.keys(ImageResizeMode)

  • tintColor: color

    Changes the color of all the non-transparent pixels to the tintColor.

  • overlayColor: string (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 http://frescolib.org/docs/rounded-corners-and-circles.html

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.

  • cover: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or larger than the corresponding dimension of the view (minus padding).

  • contain: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or less than the corresponding dimension of the view (minus padding).

  • stretch: Scale width and height independently, This may change the aspect ratio of the src.

  • repeat: Repeat the image to cover the frame of the view. The image will keep its size and aspect ratio, unless it is larger than the view, in which case it will be scaled down uniformly so that it is contained in the view.

  • center: Center the image in the view along both dimensions. If the image is larger than the view, scale it down uniformly so that it is contained in the view.

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.

  • auto: Use heuristics to pick between resize and scale.

  • resize: A software operation which changes the encoded image in memory before it gets decoded. This should be used instead of scale when the image is much larger than the view.

  • scale: The image gets drawn downscaled or upscaled. Compared to resize, scale is faster (usually hardware accelerated) and produces higher quality images. This should be used if the image is smaller than the view. It should also be used if the image is slightly bigger than the view.

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}:

  • 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 (which should be wrapped in the require('./path/to/image.png') function).
  • width, height - can be specified if known at build time, in which case these will be used to set the default <Image/> component dimensions.
  • scale - used 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.

If passing a number:

  • number - Opaque type returned by something like require('./image.jpg').

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/index.html b/docs/0.61/imagebackground/index.html index 6d655d5b558..2ed9c82b109 100644 --- a/docs/0.61/imagebackground/index.html +++ b/docs/0.61/imagebackground/index.html @@ -16,7 +16,7 @@ ImageBackground · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/imageeditor/index.html index bba5c1cd589..16fbc22cb9c 100644 --- a/docs/0.61/imageeditor/index.html +++ b/docs/0.61/imageeditor/index.html @@ -16,7 +16,7 @@ 🚧 ImageEditor · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/imagepickerios/index.html index 8e0da160370..21194fbeb49 100644 --- a/docs/0.61/imagepickerios/index.html +++ b/docs/0.61/imagepickerios/index.html @@ -16,7 +16,7 @@ 🚧 ImagePickerIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/images/index.html index e61897b9f25..7a70e3735a3 100644 --- a/docs/0.61/images/index.html +++ b/docs/0.61/images/index.html @@ -16,7 +16,7 @@ Images · React Native - + @@ -33,7 +33,7 @@
// GOOD
var icon = this.props.active
? require('./my-icon-active.png')
: require('./my-icon-inactive.png');
<Image source={icon} />;

Note that image sources required this way include size (width, height) info for the Image. If you need to scale the image dynamically (i.e. via flex), you may need to manually set { width: undefined, height: undefined } on the style attribute.

Static Non-Image Resources

The require syntax described above can be used to statically include audio, video or document files in your project as well. Most common file types are supported including .mp3, .wav, .mp4, .mov, .html and .pdf. See bundler defaults for the full list.

You can add support for other types by adding an assetExts resolver option in your Metro configuration.

A caveat is that videos must use absolute positioning instead of flexGrow, since size info is not currently passed for non-image assets. This limitation doesn't occur for videos that are linked directly into Xcode or the Assets folder for Android.

Images From Hybrid App's Resources

If you are building a hybrid app (some UIs in React Native, some UIs in platform code) you can still use images that are already bundled into the app.

For images included via Xcode asset catalogs or in the Android drawable folder, use the image name without the extension:

<Image
source={{ uri: 'app_icon' }}
style={{ width: 40, height: 40 }}
/>

For images in the Android assets folder, use the asset:/ scheme:

<Image
source={{ uri: 'asset:/app_icon.png' }}
style={{ width: 40, height: 40 }}
/>

These approaches provide no safety checks. It's up to you to guarantee that those images are available in the application. Also you have to specify image dimensions manually.

Network Images

Many of the images you will display in your app will not be available at compile time, or you will want to load some dynamically to keep the binary size down. Unlike with static resources, you will need to manually specify the dimensions of your image. It's highly recommended that you use https as well in order to satisfy App Transport Security requirements on iOS.

// GOOD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}}
style={{width: 400, height: 400}} />
// 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.

  • default: Use the native platforms default strategy.
  • reload: The data for the URL will be loaded from the originating source. No existing cache data should be used to satisfy a URL load request.
  • force-cache: The existing cached data will be used to satisfy the request, regardless of its age or expiration date. If there is no existing data in the cache corresponding the request, the data is loaded from the originating source.
  • only-if-cached: The existing cache data will be used to satisfy a request, regardless of its age or expiration date. If there is no existing data in the cache corresponding to a URL load request, no attempt is made to load the data from the originating source, and the load is considered to have failed.
<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:

  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomLeftRadius
  • borderBottomRightRadius

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/index.html b/docs/0.61/imagestore/index.html index 613f5080df5..8ae4ac01b08 100644 --- a/docs/0.61/imagestore/index.html +++ b/docs/0.61/imagestore/index.html @@ -16,7 +16,7 @@ ImageStore · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/improvingux/index.html index 51a8915bb42..3f0ca5900a1 100644 --- a/docs/0.61/improvingux/index.html +++ b/docs/0.61/improvingux/index.html @@ -16,7 +16,7 @@ Improving User Experience · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/inputaccessoryview/index.html index 61f6797a67d..725c5d3af68 100644 --- a/docs/0.61/inputaccessoryview/index.html +++ b/docs/0.61/inputaccessoryview/index.html @@ -16,7 +16,7 @@ InputAccessoryView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/integration-with-existing-apps/index.html index 5e502c87671..f73b020cf52 100644 --- a/docs/0.61/integration-with-existing-apps/index.html +++ b/docs/0.61/integration-with-existing-apps/index.html @@ -16,7 +16,7 @@ Integration with Existing Apps · React Native - + @@ -45,7 +45,7 @@
@Override
protected void onDestroy() {
super.onDestroy();
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/index.html b/docs/0.61/interactionmanager/index.html index 916aac9212f..e9482a91808 100644 --- a/docs/0.61/interactionmanager/index.html +++ b/docs/0.61/interactionmanager/index.html @@ -16,7 +16,7 @@ InteractionManager · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/intro-react-native-components/index.html index 4f34afe73a2..7661f7f6b61 100644 --- a/docs/0.61/intro-react-native-components/index.html +++ b/docs/0.61/intro-react-native-components/index.html @@ -16,7 +16,7 @@ Core Components and Native Components · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/intro-react/index.html index 4de515aa255..dea3d899d35 100644 --- a/docs/0.61/intro-react/index.html +++ b/docs/0.61/intro-react/index.html @@ -16,7 +16,7 @@ React Fundamentals · React Native - + @@ -31,7 +31,7 @@
Version: 0.61

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:

const 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:

const 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:

const Cat = () => {
return <Text>Hello, I am your cat!</Text>;
};
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/index.html b/docs/0.61/javascript-environment/index.html index 7057a773283..5b59db30182 100644 --- a/docs/0.61/javascript-environment/index.html +++ b/docs/0.61/javascript-environment/index.html @@ -16,7 +16,7 @@ JavaScript Environment · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/keyboard/index.html index 0ec17d0f7a2..e172f463150 100644 --- a/docs/0.61/keyboard/index.html +++ b/docs/0.61/keyboard/index.html @@ -16,7 +16,7 @@ Keyboard · React Native - + @@ -35,7 +35,7 @@
_keyboardDidHide() {
alert('Keyboard Hidden');
}
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:

  • keyboardWillShow
  • keyboardDidShow
  • keyboardWillHide
  • keyboardDidHide
  • keyboardWillChangeFrame
  • keyboardDidChangeFrame

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/index.html b/docs/0.61/keyboardavoidingview/index.html index 3a1582e35d9..1520dce903e 100644 --- a/docs/0.61/keyboardavoidingview/index.html +++ b/docs/0.61/keyboardavoidingview/index.html @@ -16,7 +16,7 @@ KeyboardAvoidingView · React Native - + @@ -31,7 +31,7 @@
Version: 0.61

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 position of the keyboard.

Example usage:

import { KeyboardAvoidingView } from 'react-native';
<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/index.html b/docs/0.61/layout-props/index.html index b6dd74ae27c..ad2ec1761ae 100644 --- a/docs/0.61/layout-props/index.html +++ b/docs/0.61/layout-props/index.html @@ -16,7 +16,7 @@ Layout Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/layoutanimation/index.html index 90a5006e1bd..83ddb5d00be 100644 --- a/docs/0.61/layoutanimation/index.html +++ b/docs/0.61/layoutanimation/index.html @@ -16,7 +16,7 @@ LayoutAnimation · React Native - + @@ -31,7 +31,7 @@
Version: 0.61

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 calling setState.

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 usage:

import React, { Component } from 'react';
import {
View,
Text,
TouchableOpacity,
Platform,
UIManager
} from 'react-native';
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.

  • 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:

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/index.html b/docs/0.61/libraries/index.html index c21402689eb..b29f7989cfb 100644 --- a/docs/0.61/libraries/index.html +++ b/docs/0.61/libraries/index.html @@ -16,7 +16,7 @@ Using Libraries · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/linking-libraries-ios/index.html index 1f044e6a5c2..8eb96e4cbf8 100644 --- a/docs/0.61/linking-libraries-ios/index.html +++ b/docs/0.61/linking-libraries-ios/index.html @@ -16,7 +16,7 @@ Linking Libraries · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/linking/index.html index 6c59f886c08..81b70e06289 100644 --- a/docs/0.61/linking/index.html +++ b/docs/0.61/linking/index.html @@ -16,7 +16,7 @@ Linking · React Native - + @@ -32,7 +32,7 @@
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
return [RCTLinkingManager application:application openURL:url options:options];
}

If you're targeting iOS 8.x or older, you can use the following code instead:

// iOS 8.x or older
#import <React/RCTLinkingManager.h>
- (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/index.html b/docs/0.61/listview/index.html index 035b7e41a79..88479ba2596 100644 --- a/docs/0.61/listview/index.html +++ b/docs/0.61/listview/index.html @@ -16,7 +16,7 @@ ListView · React Native - + @@ -31,7 +31,7 @@
Version: 0.61

ListView

DEPRECATED - use one of the new list components, such as FlatList or SectionList for bounded memory use, fewer bugs, better performance, an easier to use API, and more features. Check out this blog post for more details.

ListView - A core component designed for efficient display of vertically scrolling lists of changing data. The minimal API is to create a ListView.DataSource, populate it with a flat array of data blobs, and instantiate a ListView component with that data source and a renderRow callback which takes a blob from the data array and returns a renderable component.

Minimal example:

class MyComponent extends Component {
constructor() {
super();
const ds = new ListView.DataSource({
rowHasChanged: (r1, r2) => r1 !== r2
});
this.state = {
dataSource: ds.cloneWithRows(['row 1', 'row 2'])
};
}
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:

  • Only re-render changed rows - the rowHasChanged function provided to the data source tells the ListView if it needs to re-render a row because the source data has changed - see ListViewDataSource for more details.

  • Rate-limited row rendering - By default, only one row is rendered per event-loop (customizable with the pageSize prop). This breaks up the work into smaller chunks to reduce the chance of dropping frames while rendering rows.

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/index.html b/docs/0.61/listviewdatasource/index.html index 5c26c29a965..78778d9487e 100644 --- a/docs/0.61/listviewdatasource/index.html +++ b/docs/0.61/listviewdatasource/index.html @@ -16,7 +16,7 @@ ListViewDataSource · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/maskedviewios/index.html index 87f9c090e01..448e264d01f 100644 --- a/docs/0.61/maskedviewios/index.html +++ b/docs/0.61/maskedviewios/index.html @@ -16,7 +16,7 @@ 🚧 MaskedViewIOS · React Native - + @@ -31,7 +31,7 @@
Version: 0.61

🚧 MaskedViewIOS

Deprecated. Use @react-native-community/masked-view instead.

Renders the child view with a mask specified in the maskElement prop.

Example

import React from 'react';
import { MaskedViewIOS, Text, View } from 'react-native';
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/index.html b/docs/0.61/modal/index.html index ac2720189d0..d2980e960bf 100644 --- a/docs/0.61/modal/index.html +++ b/docs/0.61/modal/index.html @@ -16,7 +16,7 @@ Modal · React Native - + @@ -35,7 +35,7 @@
<TouchableHighlight
onPress={() => {
this.setModalVisible(!this.state.modalVisible);
}}>
<Text>Hide Modal</Text>
</TouchableHighlight>
</View>
</View>
</Modal>
<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.

  • 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

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

animated

Deprecated. Use the animationType prop instead.

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 8847c3fe3fd..4069ef547f5 100644 --- a/docs/0.61/more-resources/index.html +++ b/docs/0.61/more-resources/index.html @@ -16,7 +16,7 @@ More Resources · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/native-components-android/index.html index ca82ea6e6bc..b7123480dcb 100644 --- a/docs/0.61/native-components-android/index.html +++ b/docs/0.61/native-components-android/index.html @@ -16,7 +16,7 @@ Native UI Components · React Native - + @@ -39,7 +39,7 @@
class MyCustomView extends React.Component {
constructor(props) {
super(props);
this._onChange = this._onChange.bind(this);
}
_onChange(event: Event) {
if (!this.props.onChangeMessage) {
return;
}
this.props.onChangeMessage(event.nativeEvent.message);
}
render() {
return <RCTMyCustomView {...this.props} onChange={this._onChange} />;
}
}
MyCustomView.propTypes = {
/**
* Callback that is called continuously when the user is dragging the map.
*/
onChangeMessage: PropTypes.func,
...
};
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
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 6b354d456a4..22152f8e5fb 100644 --- a/docs/0.61/native-components-ios/index.html +++ b/docs/0.61/native-components-ios/index.html @@ -16,7 +16,7 @@ Native UI Components · React Native - + @@ -93,7 +93,7 @@
- (NSDictionary *)constantsToExport
{
UIDatePicker *dp = [[UIDatePicker alloc] init];
[dp layoutIfNeeded];
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/index.html b/docs/0.61/native-modules-android/index.html index 3b3041e0ce2..ad0d5742111 100644 --- a/docs/0.61/native-modules-android/index.html +++ b/docs/0.61/native-modules-android/index.html @@ -16,7 +16,7 @@ Native Modules · React Native - + @@ -80,7 +80,7 @@
@Override
public void onHostPause() {
// Activity `onPause`
}
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}
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 a3385900ac7..87f4239a55c 100644 --- a/docs/0.61/native-modules-ios/index.html +++ b/docs/0.61/native-modules-ios/index.html @@ -16,7 +16,7 @@ Native Modules · React Native - + @@ -68,7 +68,7 @@
RCT_EXTERN_METHOD(addEvent:(NSString *)name location:(NSString *)location date:(nonnull NSNumber *)date)
@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/index.html b/docs/0.61/native-modules-setup/index.html index 3f55c6ee270..245c322391c 100644 --- a/docs/0.61/native-modules-setup/index.html +++ b/docs/0.61/native-modules-setup/index.html @@ -16,7 +16,7 @@ Native Modules Setup · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/navigation/index.html index c34aa678c3e..994c62fc981 100644 --- a/docs/0.61/navigation/index.html +++ b/docs/0.61/navigation/index.html @@ -16,7 +16,7 @@ Navigating Between Screens · React Native - + @@ -33,7 +33,7 @@
const Stack = createStackNavigator();
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/index.html b/docs/0.61/netinfo/index.html index 50530d2f8a1..05edf7bc2c9 100644 --- a/docs/0.61/netinfo/index.html +++ b/docs/0.61/netinfo/index.html @@ -16,7 +16,7 @@ NetInfo · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/network/index.html index 41e5647327d..b558aa892f4 100644 --- a/docs/0.61/network/index.html +++ b/docs/0.61/network/index.html @@ -16,7 +16,7 @@ Networking · React Native - + @@ -36,7 +36,7 @@
ws.onerror = (e) => {
// an error occurred
console.log(e.message);
};
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

  • redirect:manual
  • credentials:omit
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 9c5b13e76d4..439ff9a3311 100644 --- a/docs/0.61/optimizing-flatlist-configuration/index.html +++ b/docs/0.61/optimizing-flatlist-configuration/index.html @@ -16,7 +16,7 @@ Optimizing Flatlist Configuration · React Native - + @@ -33,7 +33,7 @@
<FlatList
data={items}
renderItem={renderItem}
/>
// ...
}
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 8065ee2022b..ac8ad51000b 100644 --- a/docs/0.61/out-of-tree-platforms/index.html +++ b/docs/0.61/out-of-tree-platforms/index.html @@ -16,7 +16,7 @@ Out-of-Tree Platforms · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/panresponder/index.html index ae4138372dc..99e89f5852b 100644 --- a/docs/0.61/panresponder/index.html +++ b/docs/0.61/panresponder/index.html @@ -16,7 +16,7 @@ PanResponder · React Native - + @@ -32,7 +32,7 @@
onPanResponderGrant: (evt, gestureState) => {
// The gesture has started. Show visual feedback so the user knows
// what is happening!
// gestureState.d{x,y} will be set to zero now
},
onPanResponderMove: (evt, gestureState) => {
// The most recent move distance is gestureState.move{X,Y}
// The accumulated gesture distance since becoming responder is
// gestureState.d{x,y}
},
onPanResponderTerminationRequest: (evt, gestureState) =>
true,
onPanResponderRelease: (evt, gestureState) => {
// The user has released all touches while this view is the
// responder. This typically means a gesture has succeeded
},
onPanResponderTerminate: (evt, gestureState) => {
// Another component has become the responder, so this gesture
// should be cancelled
},
onShouldBlockNativeResponder: (evt, gestureState) => {
// Returns whether this component should block native components from becoming the JS
// responder. Returns true by default. Is currently only supported on android.
return true;
}
});
}
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:

  • onMoveShouldSetPanResponder: (e, gestureState) => {...}
  • onMoveShouldSetPanResponderCapture: (e, gestureState) => {...}
  • onStartShouldSetPanResponder: (e, gestureState) => {...}
  • onStartShouldSetPanResponderCapture: (e, gestureState) => {...}
  • onPanResponderReject: (e, gestureState) => {...}
  • onPanResponderGrant: (e, gestureState) => {...}
  • onPanResponderStart: (e, gestureState) => {...}
  • onPanResponderEnd: (e, gestureState) => {...}
  • onPanResponderRelease: (e, gestureState) => {...}
  • onPanResponderMove: (e, gestureState) => {...}
  • onPanResponderTerminate: (e, gestureState) => {...}
  • onPanResponderTerminationRequest: (e, gestureState) => {...}
  • onShouldBlockNativeResponder: (e, gestureState) => {...}

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/index.html b/docs/0.61/performance/index.html index 9c5f2a8c221..2cfcfe839e5 100644 --- a/docs/0.61/performance/index.html +++ b/docs/0.61/performance/index.html @@ -16,7 +16,7 @@ Performance · React Native - + @@ -42,7 +42,7 @@
const config = {
transformer: {
getTransformOptions: () => {
const moduleMap = {};
modulePaths.forEach(path => {
if (fs.existsSync(path)) {
moduleMap[resolve(path)] = true;
}
});
return {
preloadedModules: moduleMap,
transform: { inlineRequires: { blacklist: moduleMap } },
};
},
},
projectRoot:ROOT_FOLDER,
};
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/index.html b/docs/0.61/permissionsandroid/index.html index f8415a462ee..e8ec767c4cc 100644 --- a/docs/0.61/permissionsandroid/index.html +++ b/docs/0.61/permissionsandroid/index.html @@ -16,7 +16,7 @@ PermissionsAndroid · React Native - + @@ -31,7 +31,7 @@
Version: 0.61

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

import { PermissionsAndroid } from 'react-native';
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:

  • 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.61/picker-item/index.html b/docs/0.61/picker-item/index.html index 17fa53f2ea0..fd155b784c4 100644 --- a/docs/0.61/picker-item/index.html +++ b/docs/0.61/picker-item/index.html @@ -16,7 +16,7 @@ Picker.Item · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/picker-style-props/index.html index d11807c2f50..9538d9ac431 100644 --- a/docs/0.61/picker-style-props/index.html +++ b/docs/0.61/picker-style-props/index.html @@ -16,7 +16,7 @@ Picker Style Props · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.61/picker/index.html b/docs/0.61/picker/index.html index 48b053c5758..8a845a7ea20 100644 --- a/docs/0.61/picker/index.html +++ b/docs/0.61/picker/index.html @@ -16,7 +16,7 @@ Picker · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/pickerios/index.html index 6b3ffce4e6c..20f935e7d45 100644 --- a/docs/0.61/pickerios/index.html +++ b/docs/0.61/pickerios/index.html @@ -16,7 +16,7 @@ 🚧 PickerIOS · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.61/pixelratio/index.html b/docs/0.61/pixelratio/index.html index 91ab8515ac6..571d435a0b7 100644 --- a/docs/0.61/pixelratio/index.html +++ b/docs/0.61/pixelratio/index.html @@ -16,7 +16,7 @@ PixelRatio · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/platform-specific-code/index.html index ed8d35cdee9..fccd4d1aee5 100644 --- a/docs/0.61/platform-specific-code/index.html +++ b/docs/0.61/platform-specific-code/index.html @@ -16,7 +16,7 @@ Platform Specific Code · React Native - + @@ -35,7 +35,7 @@
if (Platform.Version === 25) {
console.log('Running on Nougat!');
}

Detecting the iOS version

On iOS, the Version is a result of -[UIDevice systemVersion], which is a string with the current version of the operating system. An example of the system version is "10.3". For example, to detect the major version number on iOS:

import { Platform } from 'react-native';
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/index.html b/docs/0.61/profiling/index.html index e98b0e98ab3..6a08d10e1c8 100644 --- a/docs/0.61/profiling/index.html +++ b/docs/0.61/profiling/index.html @@ -16,7 +16,7 @@ Profiling · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/progressbarandroid/index.html index 70062f27593..f6fd5fc934a 100644 --- a/docs/0.61/progressbarandroid/index.html +++ b/docs/0.61/progressbarandroid/index.html @@ -16,7 +16,7 @@ 🚧 ProgressBarAndroid · React Native - + @@ -32,7 +32,7 @@
export default class App extends Component {
render() {
return (
<View style={styles.container}>
<ProgressBarAndroid />
<ProgressBarAndroid styleAttr="Horizontal" />
<ProgressBarAndroid
styleAttr="Horizontal"
color="#2196F3"
/>
<ProgressBarAndroid
styleAttr="Horizontal"
indeterminate={false}
progress={0.5}
/>
</View>
);
}
}
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:

  • 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.61/progressviewios/index.html b/docs/0.61/progressviewios/index.html index 20b2762fe33..95ad18706d8 100644 --- a/docs/0.61/progressviewios/index.html +++ b/docs/0.61/progressviewios/index.html @@ -16,7 +16,7 @@ 🚧 ProgressViewIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/props/index.html index 55ad38d2a97..8d94fb5b840 100644 --- a/docs/0.61/props/index.html +++ b/docs/0.61/props/index.html @@ -16,7 +16,7 @@ Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/publishing-forks/index.html index 812e977b36a..ddd8141484c 100644 --- a/docs/0.61/publishing-forks/index.html +++ b/docs/0.61/publishing-forks/index.html @@ -16,7 +16,7 @@ Publish your own version of react native · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/publishing-to-app-store/index.html index 15c96b7450b..1ff246752c7 100644 --- a/docs/0.61/publishing-to-app-store/index.html +++ b/docs/0.61/publishing-to-app-store/index.html @@ -16,7 +16,7 @@ Publishing to Apple App Store · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/pushnotificationios/index.html index 8c14c1d048f..15f0a5b6244 100644 --- a/docs/0.61/pushnotificationios/index.html +++ b/docs/0.61/pushnotificationios/index.html @@ -16,7 +16,7 @@ 🚧 PushNotificationIOS · React Native - + @@ -33,7 +33,7 @@
return YES;
}
//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:

  • alertBody : The message displayed in the notification alert.
  • alertTitle : The text displayed as the title of the notification alert.
  • alertAction : The "action" displayed beneath an actionable notification. Defaults to "view";
  • soundName : The sound played when the notification is fired (optional).
  • isSilent : If true, the notification will appear without sound (optional).
  • category : The category of this notification, required for actionable notifications (optional).
  • userInfo : An optional object containing additional notification data.
  • applicationIconBadgeNumber (optional) : The number to display as the app's icon badge. The default value of this property is 0, which means that no badge is displayed.

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

  • fireDate : The date and time when the system should deliver the notification.
  • alertTitle : The text displayed as the title of the notification alert.
  • alertBody : The message displayed in the notification alert.
  • alertAction : The "action" displayed beneath an actionable notification. Defaults to "view";
  • soundName : The sound played when the notification is fired (optional).
  • isSilent : If true, the notification will appear without sound (optional).
  • category : The category of this notification, required for actionable notifications (optional).
  • userInfo : An optional object containing additional notification data.
  • applicationIconBadgeNumber (optional) : The number to display as the app's icon badge. Setting the number to 0 removes the icon badge.
  • repeatInterval : The interval to repeat as a string. Possible values: minute, hour, day, week, month, year.

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:

  • identifier : The identifier of this notification.
  • title : The title of this notification.
  • body : The body of this notification.
  • category : The category of this notification, if has one.
  • userInfo : An optional object containing additional notification data.
  • thread-id : The thread identifier of this notification, if has one.

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:

  • notification : Fired when a remote notification is received. The handler will be invoked with an instance of PushNotificationIOS.
  • localNotification : Fired when a local notification is received. The handler will be invoked with an instance of PushNotificationIOS.
  • register: Fired when the user registers for remote notifications. The handler will be invoked with a hex string representing the deviceToken.
  • registrationError: Fired when the user fails to register for remote notifications. Typically occurs when APNS is having issues, or the device is a simulator. The handler will be invoked with {message: string, code: number, details: any}.

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:

  • alert
  • badge
  • sound

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:

  • alert :boolean
  • badge :boolean
  • sound :boolean

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/index.html b/docs/0.61/ram-bundles-inline-requires/index.html index 171e2d82fed..a505eb86374 100644 --- a/docs/0.61/ram-bundles-inline-requires/index.html +++ b/docs/0.61/ram-bundles-inline-requires/index.html @@ -16,7 +16,7 @@ RAM Bundles and Inline Requires · React Native - + @@ -42,7 +42,7 @@
const config = {
transformer: {
getTransformOptions: () => {
const moduleMap = {};
modulePaths.forEach((path) => {
if (fs.existsSync(path)) {
moduleMap[resolve(path)] = true;
}
});
return {
preloadedModules: moduleMap,
transform: { inlineRequires: { blacklist: moduleMap } }
};
}
},
projectRoot: ROOT_FOLDER
};
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/index.html b/docs/0.61/react-node/index.html index 7f07313de98..dfe103aec1f 100644 --- a/docs/0.61/react-node/index.html +++ b/docs/0.61/react-node/index.html @@ -16,7 +16,7 @@ React Node Object Type · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/refreshcontrol/index.html index 7ee76f1ac7c..6b26143c2cf 100644 --- a/docs/0.61/refreshcontrol/index.html +++ b/docs/0.61/refreshcontrol/index.html @@ -16,7 +16,7 @@ RefreshControl · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/removing-default-permissions/index.html index cc91a129750..0ab2aefb301 100644 --- a/docs/0.61/removing-default-permissions/index.html +++ b/docs/0.61/removing-default-permissions/index.html @@ -16,7 +16,7 @@ Removing Default Permissions · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/running-on-device/index.html index 912c598a55e..fba3bd5ac75 100644 --- a/docs/0.61/running-on-device/index.html +++ b/docs/0.61/running-on-device/index.html @@ -16,7 +16,7 @@ Running On Device · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/running-on-simulator-ios/index.html index 4c6e6bf00f6..d9909e189c8 100644 --- a/docs/0.61/running-on-simulator-ios/index.html +++ b/docs/0.61/running-on-simulator-ios/index.html @@ -16,7 +16,7 @@ Running On Simulator · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/safeareaview/index.html index 7025f628ea3..75b85c1aa54 100644 --- a/docs/0.61/safeareaview/index.html +++ b/docs/0.61/safeareaview/index.html @@ -16,7 +16,7 @@ SafeAreaView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/scrollview/index.html index 184ba436593..e4affd3823d 100644 --- a/docs/0.61/scrollview/index.html +++ b/docs/0.61/scrollview/index.html @@ -16,7 +16,7 @@ ScrollView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/sectionlist/index.html index 1feaf3f9d38..a61cb30eccd 100644 --- a/docs/0.61/sectionlist/index.html +++ b/docs/0.61/sectionlist/index.html @@ -16,7 +16,7 @@ SectionList · React Native - + @@ -30,7 +30,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, function, 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 Class, a render function, or a rendered element.

TypeRequired
[component, function, element]No

ListFooterComponent

Rendered at the very end of the list. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
[component, function, element]No

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, 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, function, 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/index.html b/docs/0.61/segmentedcontrolios/index.html index 693b666fef9..236baea584e 100644 --- a/docs/0.61/segmentedcontrolios/index.html +++ b/docs/0.61/segmentedcontrolios/index.html @@ -16,7 +16,7 @@ 🚧 SegmentedControlIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/settings/index.html index 3cb62f7ba2b..0f92df4e78c 100644 --- a/docs/0.61/settings/index.html +++ b/docs/0.61/settings/index.html @@ -16,7 +16,7 @@ Settings · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/shadow-props/index.html index 388343a45ab..e9a1fe52d60 100644 --- a/docs/0.61/shadow-props/index.html +++ b/docs/0.61/shadow-props/index.html @@ -16,7 +16,7 @@ Shadow Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/share/index.html index a9d5349b4fe..6f24329c04f 100644 --- a/docs/0.61/share/index.html +++ b/docs/0.61/share/index.html @@ -16,7 +16,7 @@ Share · React Native - + @@ -33,7 +33,7 @@
if (result.action === Share.sharedAction) {
if (result.activityType) {
// shared with activity type of result.activityType
} else {
// shared
}
} else if (result.action === Share.dismissedAction) {
// dismissed
}
} catch (error) {
alert(error.message);
}
};
render() {
return <Button onPress={this.onShare} title="Share" />;
}
}
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 60227c8435f..dd5a6ef0e28 100644 --- a/docs/0.61/signed-apk-android/index.html +++ b/docs/0.61/signed-apk-android/index.html @@ -16,7 +16,7 @@ Publishing to Google Play Store · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/slider/index.html index b23e5c0b6fd..662ad5ec653 100644 --- a/docs/0.61/slider/index.html +++ b/docs/0.61/slider/index.html @@ -16,7 +16,7 @@ 🚧 Slider · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/snapshotviewios/index.html index a690f9e831a..de249deced5 100644 --- a/docs/0.61/snapshotviewios/index.html +++ b/docs/0.61/snapshotviewios/index.html @@ -16,7 +16,7 @@ SnapshotViewIOS · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.61/state/index.html b/docs/0.61/state/index.html index 01c82e26dc8..d9a82eed5ef 100644 --- a/docs/0.61/state/index.html +++ b/docs/0.61/state/index.html @@ -16,7 +16,7 @@ State · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/statusbar/index.html index a08a53dfc41..3fd91d12b55 100644 --- a/docs/0.61/statusbar/index.html +++ b/docs/0.61/statusbar/index.html @@ -16,7 +16,7 @@ StatusBar · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/statusbarios/index.html index 1cad2c7a20d..d45117ee990 100644 --- a/docs/0.61/statusbarios/index.html +++ b/docs/0.61/statusbarios/index.html @@ -16,7 +16,7 @@ 🚧 StatusBarIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/style/index.html index 1fb66814489..cef4e0781fd 100644 --- a/docs/0.61/style/index.html +++ b/docs/0.61/style/index.html @@ -16,7 +16,7 @@ Style · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/stylesheet/index.html index 9ae3f585ec5..cb90bd600b1 100644 --- a/docs/0.61/stylesheet/index.html +++ b/docs/0.61/stylesheet/index.html @@ -16,7 +16,7 @@ StyleSheet · React Native - + @@ -32,7 +32,7 @@
StyleSheet.flatten([styles.listItem, styles.selectedListItem]);
// returns { flex: 1, fontSize: 16, color: 'green' }

Alternative use:

var styles = StyleSheet.create({
listItem: {
flex: 1,
fontSize: 16,
color: 'white'
},
selectedListItem: {
color: 'green'
}
});
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/index.html b/docs/0.61/switch/index.html index b8668927f91..ff6d84756a4 100644 --- a/docs/0.61/switch/index.html +++ b/docs/0.61/switch/index.html @@ -16,7 +16,7 @@ Switch · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/symbolication/index.html index 5cb9784caef..9a0f1fd23c8 100644 --- a/docs/0.61/symbolication/index.html +++ b/docs/0.61/symbolication/index.html @@ -16,7 +16,7 @@ Symbolicating a stack trace · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/systrace/index.html index 2460ec7c034..76a883635ce 100644 --- a/docs/0.61/systrace/index.html +++ b/docs/0.61/systrace/index.html @@ -16,7 +16,7 @@ Systrace · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/tabbarios-item/index.html index 74bd62c931d..55abeca427c 100644 --- a/docs/0.61/tabbarios-item/index.html +++ b/docs/0.61/tabbarios-item/index.html @@ -16,7 +16,7 @@ TabBarIOS.Item · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/tabbarios/index.html index d673e84b939..af29fb30061 100644 --- a/docs/0.61/tabbarios/index.html +++ b/docs/0.61/tabbarios/index.html @@ -16,7 +16,7 @@ TabBarIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/testing-overview/index.html index 3939a226f31..1b4354605fa 100644 --- a/docs/0.61/testing-overview/index.html +++ b/docs/0.61/testing-overview/index.html @@ -16,7 +16,7 @@ Testing · React Native - + @@ -34,7 +34,7 @@
fireEvent.changeText(
getByPlaceholder('Enter grocery item'),
'banana'
);
fireEvent.press(getByText('Add the item to list'));
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:

  • For you as a developer or reviewer, it can be hard to tell whether a change in snapshot is intended or whether it's evidence of a bug. Especially large snapshots can quickly become hard to understand and their added value becomes low.
  • When snapshot is created, at that point it is considered to be correct-even in the case when the rendered output is actually wrong.
  • When a snapshot fails, it's tempting to update it using the --updateSnapshot jest option without taking proper care to investigate whether the change is expected. Certain developer discipline is thus needed.

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:

  • writing them is more time consuming compared to the other types of tests
  • they are slower to run
  • they are more prone to flakiness (a "flaky" test is a test which randomly passes and fails without any change to code)

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/index.html b/docs/0.61/text-style-props/index.html index 37f68ecbd21..36886bfb020 100644 --- a/docs/0.61/text-style-props/index.html +++ b/docs/0.61/text-style-props/index.html @@ -16,7 +16,7 @@ Text Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/text/index.html index e40da12d5c0..2d17a8d6582 100644 --- a/docs/0.61/text/index.html +++ b/docs/0.61/text/index.html @@ -16,7 +16,7 @@ Text · React Native - + @@ -34,7 +34,7 @@
// otherwise, the text will flow in its own block
// |First part |
// |and |
// |second part|

Limited Style Inheritance

On the web, the usual way to set a font family and size for the entire document is to take advantage of inherited CSS properties like so:

html {
font-family: 'lucida grande', tahoma, verdana, arial, sans-serif;
font-size: 11px;
color: #141823;
}

All elements in the document will inherit this font unless they or one of their parents specifies a new rule.

In React Native, we are more strict about it: you must wrap all the text nodes inside of a <Text> component. You cannot have a text node directly under a <View>.

// BAD: will raise exception, can't have a text node as child of a <View>
<View>
Some text
</View>
// 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:

  • (Developer) React components are designed with strong isolation in mind: You should be able to drop a component anywhere in your application, trusting that as long as the props are the same, it will look and behave the same way. Text properties that could inherit from outside of the props would break this isolation.

  • (Implementor) The implementation of React Native is also simplified. We do not need to have a fontFamily field on every single element, and we do not need to potentially traverse the tree up to the root every time we display a text node. The style inheritance is only encoded inside of the native Text component and doesn't leak to other components or the system itself.

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:

  • '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

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:

  • 'phoneNumber'
  • 'link'
  • 'email'
  • 'none'
  • 'all'
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:

  • head - The line is displayed so that the end fits in the container and the missing text at the beginning of the line is indicated by an ellipsis glyph. e.g., "...wxyz"
  • middle - The line is displayed so that the beginning and end fit in the container and the missing text in the middle is indicated by an ellipsis glyph. "ab...yz"
  • tail - The line is displayed so that the beginning fits in the container and the missing text at the end of the line is indicated by an ellipsis glyph. e.g., "abcd..."
  • clip - Lines are not drawn past the edge of the text container.

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:

  • 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

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/index.html b/docs/0.61/textinput/index.html index 756b7910168..3519a81bff1 100644 --- a/docs/0.61/textinput/index.html +++ b/docs/0.61/textinput/index.html @@ -16,7 +16,7 @@ TextInput · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/timepickerandroid/index.html index e30c53dfd11..cd78a4c793b 100644 --- a/docs/0.61/timepickerandroid/index.html +++ b/docs/0.61/timepickerandroid/index.html @@ -16,7 +16,7 @@ 🚧 TimePickerAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/timers/index.html index a6f1870cb2a..722b023a496 100644 --- a/docs/0.61/timers/index.html +++ b/docs/0.61/timers/index.html @@ -16,7 +16,7 @@ Timers · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/toastandroid/index.html index d1ee44a48b0..d735ff74277 100644 --- a/docs/0.61/toastandroid/index.html +++ b/docs/0.61/toastandroid/index.html @@ -16,7 +16,7 @@ ToastAndroid · React Native - + @@ -36,7 +36,7 @@
hideToast = () => {
this.setState({
visible: false
});
};
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/index.html b/docs/0.61/toolbarandroid/index.html index 84fd94b5d09..a3a06e4b6f0 100644 --- a/docs/0.61/toolbarandroid/index.html +++ b/docs/0.61/toolbarandroid/index.html @@ -16,7 +16,7 @@ ToolbarAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/touchablehighlight/index.html index c061cbc07d3..78b13f1e006 100644 --- a/docs/0.61/touchablehighlight/index.html +++ b/docs/0.61/touchablehighlight/index.html @@ -16,7 +16,7 @@ TouchableHighlight · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/touchablenativefeedback/index.html index 22a4999cbeb..5c2bcdf443a 100644 --- a/docs/0.61/touchablenativefeedback/index.html +++ b/docs/0.61/touchablenativefeedback/index.html @@ -16,7 +16,7 @@ TouchableNativeFeedback · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/touchableopacity/index.html index 1f7d087ea86..32b8a0b4773 100644 --- a/docs/0.61/touchableopacity/index.html +++ b/docs/0.61/touchableopacity/index.html @@ -16,7 +16,7 @@ TouchableOpacity · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/touchablewithoutfeedback/index.html index b56efa3c9c6..8417dc7d06d 100644 --- a/docs/0.61/touchablewithoutfeedback/index.html +++ b/docs/0.61/touchablewithoutfeedback/index.html @@ -16,7 +16,7 @@ TouchableWithoutFeedback · React Native - + @@ -31,7 +31,7 @@
Version: 0.61

TouchableWithoutFeedback

Do not use unless you have a very good reason. All elements that respond to press should have a visual feedback when touched.

TouchableWithoutFeedback supports only one child. If you wish to have several child components, wrap them in a View. Importantly, TouchableWithoutFeedback works by cloning its child and applying responder props to it. It is therefore required that any intermediary components pass through those props to the underlying React Native component.

Usage Example

function MyComponent(props) {
return (
<View {...props} style={{ flex: 1, backgroundColor: '#fff' }}>
<Text>My Component</Text>
</View>
);
}
<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:

  • '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

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/index.html b/docs/0.61/transforms/index.html index 8437e2a6be3..0e15e799c9c 100644 --- a/docs/0.61/transforms/index.html +++ b/docs/0.61/transforms/index.html @@ -16,7 +16,7 @@ Transforms · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/troubleshooting/index.html index 32f1c6ef2bb..acb6240e10e 100644 --- a/docs/0.61/troubleshooting/index.html +++ b/docs/0.61/troubleshooting/index.html @@ -16,7 +16,7 @@ Troubleshooting · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/tutorial/index.html index a7e3aabe95a..7341c31cf03 100644 --- a/docs/0.61/tutorial/index.html +++ b/docs/0.61/tutorial/index.html @@ -16,7 +16,7 @@ Learn the Basics · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/typescript/index.html index eaabc4f0b6a..8a18053bbd9 100644 --- a/docs/0.61/typescript/index.html +++ b/docs/0.61/typescript/index.html @@ -16,7 +16,7 @@ Using TypeScript with React Native · React Native - + @@ -37,7 +37,7 @@
<View style={styles.button}>
<Button
title="+"
onPress={onIncrement}
accessibilityLabel="increment"
color="blue"
/>
</View>
</View>
</View>
);
}
}
// 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/index.html b/docs/0.61/upgrading/index.html index eabf6ff3a46..f9baed6a35e 100644 --- a/docs/0.61/upgrading/index.html +++ b/docs/0.61/upgrading/index.html @@ -16,7 +16,7 @@ Upgrading to new React Native versions · React Native - + @@ -30,7 +30,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/usecolorscheme/index.html b/docs/0.61/usecolorscheme/index.html index 7ed84f381d4..af864c4ecfc 100644 --- a/docs/0.61/usecolorscheme/index.html +++ b/docs/0.61/usecolorscheme/index.html @@ -16,7 +16,7 @@ useColorScheme · React Native - + @@ -31,7 +31,7 @@
Version: 0.61

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.
import { Text, useColorScheme } from 'react-native';
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.61/usewindowdimensions/index.html b/docs/0.61/usewindowdimensions/index.html index a0422c49342..53611d2acb6 100644 --- a/docs/0.61/usewindowdimensions/index.html +++ b/docs/0.61/usewindowdimensions/index.html @@ -16,7 +16,7 @@ useWindowDimensions · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/using-a-listview/index.html index b23aa9e06e3..92b99d76367 100644 --- a/docs/0.61/using-a-listview/index.html +++ b/docs/0.61/using-a-listview/index.html @@ -16,7 +16,7 @@ Using List Views · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/using-a-scrollview/index.html index e2a7980a318..91124253381 100644 --- a/docs/0.61/using-a-scrollview/index.html +++ b/docs/0.61/using-a-scrollview/index.html @@ -16,7 +16,7 @@ Using a ScrollView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/vibration/index.html index c20587d061c..6c0366875ea 100644 --- a/docs/0.61/vibration/index.html +++ b/docs/0.61/vibration/index.html @@ -16,7 +16,7 @@ Vibration · React Native - + @@ -34,7 +34,7 @@
Vibration.vibrate(PATTERN, true);
// Android: wait 1s -> vibrate 2s -> wait 3s -> wait 1s -> vibrate 2s -> wait 3s -> ...
// iOS: wait 1s -> vibrate -> wait 2s -> vibrate -> wait 3s -> vibrate -> wait 1s -> vibrate -> wait 2s -> vibrate -> wait 3s -> vibrate -> ...
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/index.html b/docs/0.61/vibrationios/index.html index 636d2d2a690..b30327cebdc 100644 --- a/docs/0.61/vibrationios/index.html +++ b/docs/0.61/vibrationios/index.html @@ -16,7 +16,7 @@ VibrationIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/view-style-props/index.html index bce87108b4e..1946e24d1dc 100644 --- a/docs/0.61/view-style-props/index.html +++ b/docs/0.61/view-style-props/index.html @@ -16,7 +16,7 @@ View Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/view/index.html index 58fa0e59a16..89ef744feab 100644 --- a/docs/0.61/view/index.html +++ b/docs/0.61/view/index.html @@ -16,7 +16,7 @@ View · React Native - + @@ -30,7 +30,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/index.html b/docs/0.61/viewpagerandroid/index.html index acab2d2189e..e883553ef2c 100644 --- a/docs/0.61/viewpagerandroid/index.html +++ b/docs/0.61/viewpagerandroid/index.html @@ -16,7 +16,7 @@ 🚧 ViewPagerAndroid · React Native - + @@ -32,7 +32,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.

  • '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

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:

  • position - index of first page from the left that is currently visible
  • offset - value from range [0, 1] describing stage between page transitions. Value x means that (1 - x) fraction of the page at "position" index is visible, and x fraction of the next page is visible.
TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

  • idle, meaning there is no interaction with the page scroller happening at the time
  • dragging, meaning there is currently an interaction with the page scroller
  • settling, meaning that there was an interaction with the page scroller, and the page scroller is now finishing its closing or opening animation
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:

  • position - index of page that has been selected
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.

  • position - index of page that will be selected
TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

  • position - index of page that will be selected
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/index.html b/docs/0.61/virtualizedlist/index.html index 5d8933d71de..b2a0756c587 100644 --- a/docs/0.61/virtualizedlist/index.html +++ b/docs/0.61/virtualizedlist/index.html @@ -16,7 +16,7 @@ VirtualizedList · React Native - + @@ -30,7 +30,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 Class, a render function, or a rendered element.

TypeRequired
component, function, 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 Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListFooterComponentStyle

Styling for internal View for ListFooterComponent

TypeRequired
ViewStylePropNo

ListHeaderComponent

Rendered at the top of all the items. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, 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 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/index.html b/docs/0.61/webview/index.html index 5b620f02354..7509a817e68 100644 --- a/docs/0.61/webview/index.html +++ b/docs/0.61/webview/index.html @@ -16,7 +16,7 @@ 🚧 WebView · React Native - + @@ -32,7 +32,7 @@
class MyWeb extends Component {
render() {
return (
<WebView
source={{
uri: 'https://github.com/facebook/react-native'
}}
style={{ marginTop: 20 }}
/>
);
}
}

Minimal example with inline HTML:

import React, { Component } from 'react';
import { WebView } from 'react-native';
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

  • uri (string) - The URI to load in the WebView. Can be a local or remote file.
  • method (string) - The HTTP Method to use. Defaults to GET if not specified. On Android, the only supported methods are GET and POST.
  • headers (object) - Additional HTTP headers to send with the request. On Android, this can only be used with GET requests.
  • body (string) - The 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. On Android, this can only be used with POST requests.

Static HTML

  • html (string) - A static HTML page to display in the WebView.
  • baseUrl (string) - The base URL to be used for any relative links in the 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:

  • component (any)
  • props (object)
  • viewManager (object)
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:

  • normal: 0.998
  • fast: 0.99 (the default for iOS web view)
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:

  • never (default) - WebView will not allow a secure origin to load content from an insecure origin.
  • always - WebView will allow a secure origin to load content from any other origin, even if that origin is insecure.
  • compatibility - WebView will attempt to be compatible with the approach of a modern web browser with regard to mixed content.
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:

  • phoneNumber
  • link
  • address
  • calendarEvent
  • none
  • all

With the new WebKit implementation, we have three new values:

  • trackingNumber
  • flightNumber
  • lookupSuggestion
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/index.html b/docs/0.62/_getting-started-linux-android/index.html index b3e19c43e30..5c42aac91bb 100644 --- a/docs/0.62/_getting-started-linux-android/index.html +++ b/docs/0.62/_getting-started-linux-android/index.html @@ -16,7 +16,7 @@ _getting-started-linux-android · React Native - + @@ -31,7 +31,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 intallation 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/index.html b/docs/0.62/_getting-started-macos-android/index.html index 86946bff649..01824c32851 100644 --- a/docs/0.62/_getting-started-macos-android/index.html +++ b/docs/0.62/_getting-started-macos-android/index.html @@ -16,7 +16,7 @@ _getting-started-macos-android · React Native - + @@ -31,7 +31,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 cask install 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 intallation 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/index.html b/docs/0.62/_getting-started-macos-ios/index.html index d970e417e05..195d3a2cb2f 100644 --- a/docs/0.62/_getting-started-macos-ios/index.html +++ b/docs/0.62/_getting-started-macos-ios/index.html @@ -16,7 +16,7 @@ _getting-started-macos-ios · React Native - + @@ -31,7 +31,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/index.html b/docs/0.62/_getting-started-windows-android/index.html index ace11825f38..5c95cabf3c0 100644 --- a/docs/0.62/_getting-started-windows-android/index.html +++ b/docs/0.62/_getting-started-windows-android/index.html @@ -16,7 +16,7 @@ _getting-started-windows-android · React Native - + @@ -31,7 +31,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 intallation 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/index.html b/docs/0.62/_integration-with-exisiting-apps-java/index.html index 59c100af693..88b83c50268 100644 --- a/docs/0.62/_integration-with-exisiting-apps-java/index.html +++ b/docs/0.62/_integration-with-exisiting-apps-java/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-java · React Native - + @@ -45,7 +45,7 @@
@Override
protected void onDestroy() {
super.onDestroy();
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/index.html b/docs/0.62/_integration-with-exisiting-apps-objc/index.html index 5f9af196682..44586af5af1 100644 --- a/docs/0.62/_integration-with-exisiting-apps-objc/index.html +++ b/docs/0.62/_integration-with-exisiting-apps-objc/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-objc · React Native - + @@ -39,7 +39,7 @@
// Module name
AppRegistry.registerComponent('RNHighScores', () => RNHighScores);

RNHighScores is the name of your module that will be used when you add a view to React Native from within your iOS application.

The Magic: RCTRootView

Now that your React Native component is created via index.js, you need to add that component to a new or existing ViewController. The easiest path to take is to optionally create an event path to your component and then add that component to an existing ViewController.

We will tie our React Native component with a new native view in the ViewController that will actually contain it called RCTRootView .

1. Create an Event Path

You can add a new link on the main game menu to go to the "High Score" React Native page.

Event Path

2. Event Handler

We will now add an event handler from the menu link. A method will be added to the main ViewController of your application. This is where RCTRootView comes into play.

When you build a React Native application, you use the Metro bundler to create an index.bundle that will be served by the React Native server. Inside index.bundle will be our RNHighScore module. So, we need to point our RCTRootView to the location of the index.bundle resource (via NSURL) and tie it to the module.

We will, for debugging purposes, log that the event handler was invoked. Then, we will create a string with the location of our React Native code that exists inside the index.bundle. Finally, we will create the main RCTRootView. Notice how we provide RNHighScores as the moduleName that we created above when writing the code for our React Native component.

First import the RCTRootView header.

#import <React/RCTRootView.h>

The initialProperties are here for illustration purposes so we have some data for our high score screen. In our React Native component, we will use this.props to get access to that data.

- (IBAction)highScoreButtonPressed:(id)sender {
NSLog(@"High Score Button Pressed");
NSURL *jsCodeLocation = [NSURL URLWithString:@"http://localhost:8081/index.bundle?platform=ios"];
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/index.html b/docs/0.62/_integration-with-exisiting-apps-swift/index.html index 1a768f23a42..7acd32e1d8c 100644 --- a/docs/0.62/_integration-with-exisiting-apps-swift/index.html +++ b/docs/0.62/_integration-with-exisiting-apps-swift/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-swift · React Native - + @@ -40,7 +40,7 @@
// Module name
AppRegistry.registerComponent('RNHighScores', () => RNHighScores);

RNHighScores is the name of your module that will be used when you add a view to React Native from within your iOS application.

The Magic: RCTRootView

Now that your React Native component is created via index.js, you need to add that component to a new or existing ViewController. The easiest path to take is to optionally create an event path to your component and then add that component to an existing ViewController.

We will tie our React Native component with a new native view in the ViewController that will actually contain it called RCTRootView .

1. Create an Event Path

You can add a new link on the main game menu to go to the "High Score" React Native page.

Event Path

2. Event Handler

We will now add an event handler from the menu link. A method will be added to the main ViewController of your application. This is where RCTRootView comes into play.

When you build a React Native application, you use the Metro bundler to create an index.bundle that will be served by the React Native server. Inside index.bundle will be our RNHighScore module. So, we need to point our RCTRootView to the location of the index.bundle resource (via NSURL) and tie it to the module.

We will, for debugging purposes, log that the event handler was invoked. Then, we will create a string with the location of our React Native code that exists inside the index.bundle. Finally, we will create the main RCTRootView. Notice how we provide RNHighScores as the moduleName that we created above when writing the code for our React Native component.

First import the React library.

import React

The initialProperties are here for illustration purposes so we have some data for our high score screen. In our React Native component, we will use this.props to get access to that data.

@IBAction func highScoreButtonTapped(sender : UIButton) {
NSLog("Hello")
let jsCodeLocation = URL(string: "http://localhost:8081/index.bundle?platform=ios")
let mockData:NSDictionary = ["scores":
[
["name":"Alex", "value":"42"],
["name":"Joel", "value":"10"]
]
]
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/index.html b/docs/0.62/accessibility/index.html index 8e7b578df42..18da112f78e 100644 --- a/docs/0.62/accessibility/index.html +++ b/docs/0.62/accessibility/index.html @@ -16,7 +16,7 @@ Accessibility · React Native - + @@ -32,7 +32,7 @@
if (Platform.OS === 'android') {
UIManager.sendAccessibilityEvent(
findNodeHandle(this),
UIManager.AccessibilityEventTypes.typeViewFocused
);
}

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.

Testing TalkBack Support (Android)

To enable TalkBack, go to the Settings app on your Android device or emulator. Tap Accessibility, then TalkBack. Toggle the "Use service" switch to enable or disable it.

P.S. Android emulator doesn’t have TalkBack by default. To install it:

  1. Download TalkBack file here: https://google-talkback.en.uptodown.com/android
  2. Drag the downloaded .apk file into the emulator

You can use the volume key shortcut to toggle TalkBack. To turn on the volume key shortcut, go to the Settings app, then Accessibility. At the top, turn on Volume key shortcut.

To use the volume key shortcut, press both volume keys for 3 seconds to start an accessibility tool.

Additionally, if you prefer, you can toggle TalkBack via command line with:

# disable
adb shell settings put secure enabled_accessibility_services com.android.talkback/com.google.android.marvin.talkback.TalkBackService
# 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/index.html b/docs/0.62/accessibilityinfo/index.html index b41810da916..ae7c3c14588 100644 --- a/docs/0.62/accessibilityinfo/index.html +++ b/docs/0.62/accessibilityinfo/index.html @@ -16,7 +16,7 @@ AccessibilityInfo · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/actionsheetios/index.html index 36da7c062b8..99f0fb0a323 100644 --- a/docs/0.62/actionsheetios/index.html +++ b/docs/0.62/actionsheetios/index.html @@ -16,7 +16,7 @@ ActionSheetIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/activityindicator/index.html index 74017757837..aa1e5140c1c 100644 --- a/docs/0.62/activityindicator/index.html +++ b/docs/0.62/activityindicator/index.html @@ -16,7 +16,7 @@ ActivityIndicator · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/alert/index.html index 14a01cf7f3e..ee8b5e01c00 100644 --- a/docs/0.62/alert/index.html +++ b/docs/0.62/alert/index.html @@ -16,7 +16,7 @@ Alert · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/alertios/index.html index cf3db098276..9a6c8fcfa2b 100644 --- a/docs/0.62/alertios/index.html +++ b/docs/0.62/alertios/index.html @@ -16,7 +16,7 @@ 🚧 AlertIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/animated/index.html index 39dd0b99e25..79cde2a6743 100644 --- a/docs/0.62/animated/index.html +++ b/docs/0.62/animated/index.html @@ -16,7 +16,7 @@ Animated · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/animatedvalue/index.html index 4dafa8308ce..fa7d2b192af 100644 --- a/docs/0.62/animatedvalue/index.html +++ b/docs/0.62/animatedvalue/index.html @@ -16,7 +16,7 @@ AnimatedValue · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/animatedvaluexy/index.html index 9b2510b616b..711640aff47 100644 --- a/docs/0.62/animatedvaluexy/index.html +++ b/docs/0.62/animatedvaluexy/index.html @@ -16,7 +16,7 @@ AnimatedValueXY · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/animations/index.html index e32f0a129da..9aa9ff958cb 100644 --- a/docs/0.62/animations/index.html +++ b/docs/0.62/animations/index.html @@ -16,7 +16,7 @@ Animations · React Native - + @@ -31,7 +31,7 @@
Version: 0.62

Animations

Animations are very important to create a great user experience. Stationary objects must overcome inertia as they start moving. Objects in motion have momentum and rarely come to a stop immediately. Animations allow you to convey physically believable motion in your interface.

React Native provides two complementary animation systems: Animated for granular and interactive control of specific values, and LayoutAnimation for animated global layout transactions.

Animated API

The Animated API is designed to concisely express a wide variety of interesting animation and interaction patterns in a very performant way. Animated focuses on declarative relationships between inputs and outputs, with configurable transforms in between, and start/stop methods to control time-based animation execution.

Animated exports six animatable component types: View, Text, Image, ScrollView, FlatList and SectionList, but you can also create your own using Animated.createAnimatedComponent().

For example, a container view that fades in when it is mounted may look like this:

Let's break down what's happening here. In the FadeInView constructor, a new Animated.Value called fadeAnim is initialized as part of state. The opacity property on the View is mapped to this animated value. Behind the scenes, the numeric value is extracted and used to set opacity.

When the component mounts, the opacity is set to 0. Then, an easing animation is started on the fadeAnim animated value, which will update all of its dependent mappings (in this case, only the opacity) on each frame as the value animates to the final value of 1.

This is done in an optimized way that is faster than calling setState and re-rendering. Because the entire configuration is declarative, we will be able to implement further optimizations that serialize the configuration and runs the animation on a high-priority thread.

Configuring animations

Animations are heavily configurable. Custom and predefined easing functions, delays, durations, decay factors, spring constants, and more can all be tweaked depending on the type of animation.

Animated provides several animation types, the most commonly used one being Animated.timing(). It supports animating a value over time using one of various predefined easing functions, or you can use your own. Easing functions are typically used in animation to convey gradual acceleration and deceleration of objects.

By default, timing will use an easeInOut curve that conveys gradual acceleration to full speed and concludes by gradually decelerating to a stop. You can specify a different easing function by passing an easing parameter. Custom duration or even a delay before the animation starts is also supported.

For example, if we want to create a 2-second long animation of an object that slightly backs up before moving to its final position:

Animated.timing(this.state.xPosition, {
toValue: 100,
easing: Easing.back(),
duration: 2000
}).start();

Take a look at the Configuring animations section of the Animated API reference to learn more about all the config parameters supported by the built-in animations.

Composing animations

Animations can be combined and played in sequence or in parallel. Sequential animations can play immediately after the previous animation has finished, or they can start after a specified delay. The Animated API provides several methods, such as sequence() and delay(), each of which take an array of animations to execute and automatically calls start()/stop() as needed.

For example, the following animation coasts to a stop, then it springs back while twirling in parallel:

Animated.sequence([
// decay, then spring to start and twirl
Animated.decay(position, {
// coast to a stop
velocity: { x: gestureState.vx, y: gestureState.vy }, // velocity from gesture release
deceleration: 0.997
}),
Animated.parallel([
// after decay, in parallel:
Animated.spring(position, {
toValue: { x: 0, y: 0 } // return to start
}),
Animated.timing(twirl, {
// and twirl
toValue: 360
})
])
]).start(); // start the sequence group

If one animation is stopped or interrupted, then all other animations in the group are also stopped. Animated.parallel has a stopTogether option that can be set to false to disable this.

You can find a full list of composition methods in the Composing animations section of the Animated API reference.

Combining animated values

You can combine two animated values via addition, multiplication, division, or modulo to make a new animated value.

There are some cases where an animated value needs to invert another animated value for calculation. An example is inverting a scale (2x --> 0.5x):

const a = new Animated.Value(1);
const b = Animated.divide(1, a);
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:

  • spring.stopAnimation(callback) will stop the animation and invoke callback with the final value. This is useful when making gesture transitions.
  • spring.addListener(callback) will invoke callback asynchronously while the animation is running, providing a recent value. This is useful for triggering state changes, for example snapping a bobble to a new option as the user drags it closer, because these larger state changes are less sensitive to a few frames of lag compared to continuous gestures like panning which need to run at 60 fps.

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/index.html b/docs/0.62/app-extensions/index.html index c10bc502031..44b33da518b 100644 --- a/docs/0.62/app-extensions/index.html +++ b/docs/0.62/app-extensions/index.html @@ -16,7 +16,7 @@ App Extensions · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/appearance/index.html index 21c3f11caab..67f18c64b6f 100644 --- a/docs/0.62/appearance/index.html +++ b/docs/0.62/appearance/index.html @@ -16,7 +16,7 @@ Appearance · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/appregistry/index.html index 657415e286d..cf445ffb2bc 100644 --- a/docs/0.62/appregistry/index.html +++ b/docs/0.62/appregistry/index.html @@ -16,7 +16,7 @@ AppRegistry · React Native - + @@ -32,7 +32,7 @@
const App = (props) => (
<View>
<Text>App1</Text>
</View>
);
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:

  • 'appKey' (string)- Required.
  • 'component' (ComponentProvider) - Optional.
  • 'run' (Function) - Optional.
  • 'section' (boolean) - Optional.

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:

  • 'component' (ComponentProvider).
  • 'run' (Function).

getRunnable()

static getRunnable(appKey)

Returns a Runnable object which consist of:

  • 'component' (ComponentProvider).
  • 'run' (Function).

getRegistry()

static getRegistry()

Returns a type Registry which consist of:

  • 'sections' (Array of strings).
  • 'runnables' (Runnables).

setComponentProviderInstrumentationHook()

static setComponentProviderInstrumentationHook(hook)

Parameters:

NameTypeRequiredDescription
hookFunctionyesSee below.

A valid hook accepts the following as arguments:

  • 'component' (ComponentProvider)- Required.
  • 'scopedPerformanceLogger' (IPerformanceLogger)- Required.

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.
  • A valid TaskProvider is a function that returns a Task.
  • A Task is a function that accepts any data as argument and returns a Promise that resolves to undefined.

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.
  • A valid TaskProvider is a function that returns a Task.
  • A Task is a function that accepts any data as argument and returns a Promise that resolves to undefined.
  • A valid TaskCancelProvider is a function that returns a TaskCanceller.
  • A TaskCanceller is a function that accepts no argument and returns void.

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/index.html b/docs/0.62/appstate/index.html index d8fde1c1908..430b9e75993 100644 --- a/docs/0.62/appstate/index.html +++ b/docs/0.62/appstate/index.html @@ -16,7 +16,7 @@ AppState · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/asyncstorage/index.html index 3a3ab4da2c0..ea0e40d04b2 100644 --- a/docs/0.62/asyncstorage/index.html +++ b/docs/0.62/asyncstorage/index.html @@ -16,7 +16,7 @@ 🚧 AsyncStorage · React Native - + @@ -38,7 +38,7 @@
AsyncStorage.multiSet(multi_set_pairs, (err) => {
AsyncStorage.multiMerge(multi_merge_pairs, (err) => {
AsyncStorage.multiGet(['UID234', 'UID345'], (err, stores) => {
stores.map((result, i, store) => {
let key = store[i][0];
let val = store[i][1];
console.log(key, val);
});
});
});
});
// 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/index.html b/docs/0.62/backandroid/index.html index 68424dedfe6..9497b031148 100644 --- a/docs/0.62/backandroid/index.html +++ b/docs/0.62/backandroid/index.html @@ -16,7 +16,7 @@ BackAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/backhandler/index.html index 1a1733455a3..4554202823c 100644 --- a/docs/0.62/backhandler/index.html +++ b/docs/0.62/backhandler/index.html @@ -16,7 +16,7 @@ BackHandler · React Native - + @@ -31,7 +31,7 @@
Version: 0.62

BackHandler

The Backhandler API detects hardware button presses for back navigation, lets you register event listeners for the system's back action, and lets you control how your application responds. It is Android-only.

The event subscriptions are called in reverse order (i.e. the last registered subscription is called first).

  • If one subscription returns true, then subscriptions registered earlier will not be called.
  • If no subscription returns true or none are registered, it programmatically invokes the default back button functionality to exit the app.

Warning for modal users: If your app shows an opened Modal, BackHandler will not publish any events (see Modal docs).

Pattern

BackHandler.addEventListener('hardwareBackPress', function() {
/**
* this.onMainScreen and this.goBack are just examples,
* you need to use your own implementation here.
*
* Typically you would use the navigator here to go to the last state.
*/
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/index.html b/docs/0.62/building-for-tv/index.html index 0e3ffc5a589..8de7c15368b 100644 --- a/docs/0.62/building-for-tv/index.html +++ b/docs/0.62/building-for-tv/index.html @@ -16,7 +16,7 @@ Building For TV Devices · React Native - + @@ -35,7 +35,7 @@
componentDidMount() {
this._enableTVEventHandler();
}
componentWillUnmount() {
this._disableTVEventHandler();
}
}

  • Dev Menu support: On the simulator, cmd-M will bring up the developer menu, similar to Android. To bring it up on a real Android TV device, press the menu button or long press the fast-forward button on the remote. (Please do not shake the Android TV device, that will not work :) )

  • Known issues:

    • TextInput components do not work for now (i.e. they cannot receive focus automatically, see this comment).
      • It is however possible to use a ref to manually trigger inputRef.current.focus().
      • You can wrap your input inside a TouchableWithoutFeedback component and trigger focus in the onFocus event of that touchable. This enables opening the keyboard via the arrow keys.
      • The keyboard might reset its state after each keypress (this might only happen inside the Android TV emulator).
    • The content of Modal components cannot receive focus, see this issue for details.
Edit this page
Last updated on
- + diff --git a/docs/0.62/button/index.html b/docs/0.62/button/index.html index 8f51c914912..fbdedfd672a 100644 --- a/docs/0.62/button/index.html +++ b/docs/0.62/button/index.html @@ -16,7 +16,7 @@ Button · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/cameraroll/index.html index 2926a301d01..6a216a3be19 100644 --- a/docs/0.62/cameraroll/index.html +++ b/docs/0.62/cameraroll/index.html @@ -16,7 +16,7 @@ 🚧 CameraRoll · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/checkbox/index.html index 5f386e9f8cd..1c9247237e2 100644 --- a/docs/0.62/checkbox/index.html +++ b/docs/0.62/checkbox/index.html @@ -16,7 +16,7 @@ 🚧 CheckBox · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/clipboard/index.html index 9afda4ee553..bd624b3c473 100644 --- a/docs/0.62/clipboard/index.html +++ b/docs/0.62/clipboard/index.html @@ -16,7 +16,7 @@ 🚧 Clipboard · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/colors/index.html index 90922134065..ed1d791b905 100644 --- a/docs/0.62/colors/index.html +++ b/docs/0.62/colors/index.html @@ -16,7 +16,7 @@ Color Reference · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/communication-android/index.html index 97a3d8bcdd5..a7f9c4fe982 100644 --- a/docs/0.62/communication-android/index.html +++ b/docs/0.62/communication-android/index.html @@ -16,7 +16,7 @@ Communication between native and React Native · React Native - + @@ -32,7 +32,7 @@
export default class ImageBrowserApp extends React.Component {
renderImage(imgURI) {
return <Image source={{ uri: imgURI }} />;
}
render() {
return <View>{this.props.images.map(this.renderImage)}</View>;
}
}

ReactRootView provides a read-write property appProperties. After appProperties is set, the React Native app is re-rendered with new properties. The update is only performed when the new updated properties differ from the previous ones.

Bundle updatedProps = mReactRootView.getAppProperties();
ArrayList<String> imageList = new ArrayList<String>(Arrays.asList(
"http://foo.com/bar3.png",
"http://foo.com/bar4.png"
));
updatedProps.putStringArrayList("images", imageList);
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:

  • As events can be sent from anywhere, they can introduce spaghetti-style dependencies into your project.
  • Events share namespace, which means that you may encounter some name collisions. Collisions will not be detected statically, which makes them hard to debug.
  • If you use several instances of the same React Native component and you want to distinguish them from the perspective of your event, you'll likely need to introduce identifiers and pass them along with events (you can use the native view's reactTag as an identifier).

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/index.html b/docs/0.62/communication-ios/index.html index fefed418394..8ed4bf4d835 100644 --- a/docs/0.62/communication-ios/index.html +++ b/docs/0.62/communication-ios/index.html @@ -16,7 +16,7 @@ Communication between native and React Native · React Native - + @@ -41,7 +41,7 @@
#pragma mark - RCTRootViewDelegate
- (void)rootViewDidChangeIntrinsicSize:(RCTRootView *)rootView
{
CGRect newFrame = rootView.frame;
newFrame.size = rootView.intrinsicContentSize;
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/index.html b/docs/0.62/components-and-apis/index.html index 71cca0f612e..13171527bcf 100644 --- a/docs/0.62/components-and-apis/index.html +++ b/docs/0.62/components-and-apis/index.html @@ -16,7 +16,7 @@ Core Components and APIs · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/custom-webview-android/index.html index 53f1acd10d5..4027b5a8122 100644 --- a/docs/0.62/custom-webview-android/index.html +++ b/docs/0.62/custom-webview-android/index.html @@ -16,7 +16,7 @@ Custom WebView · React Native - + @@ -57,7 +57,7 @@
_onNavigationCompleted = (event) => {
const { onNavigationCompleted } = this.props;
onNavigationCompleted && onNavigationCompleted(event);
};
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/index.html b/docs/0.62/custom-webview-ios/index.html index ec20ac0717c..ccb696e6dbb 100644 --- a/docs/0.62/custom-webview-ios/index.html +++ b/docs/0.62/custom-webview-ios/index.html @@ -16,7 +16,7 @@ Custom WebView · React Native - + @@ -60,7 +60,7 @@
_onNavigationCompleted = (event) => {
const { onNavigationCompleted } = this.props;
onNavigationCompleted && onNavigationCompleted(event);
};
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/index.html b/docs/0.62/datepickerandroid/index.html index 6c04947fb0a..3ec699f7a7d 100644 --- a/docs/0.62/datepickerandroid/index.html +++ b/docs/0.62/datepickerandroid/index.html @@ -16,7 +16,7 @@ 🚧 DatePickerAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/datepickerios/index.html index 2d6e043c6e7..157f381f0ad 100644 --- a/docs/0.62/datepickerios/index.html +++ b/docs/0.62/datepickerios/index.html @@ -16,7 +16,7 @@ 🚧 DatePickerIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/debugging/index.html index b14b339cf34..5124c883cad 100644 --- a/docs/0.62/debugging/index.html +++ b/docs/0.62/debugging/index.html @@ -16,7 +16,7 @@ Debugging · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/devsettings/index.html index 4bab8f0e8fb..fd14cc680de 100644 --- a/docs/0.62/devsettings/index.html +++ b/docs/0.62/devsettings/index.html @@ -16,7 +16,7 @@ DevSettings · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/dimensions/index.html index a37a59ed58d..4bc732d0462 100644 --- a/docs/0.62/dimensions/index.html +++ b/docs/0.62/dimensions/index.html @@ -16,7 +16,7 @@ Dimensions · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/direct-manipulation/index.html index 9e56ccd7393..b4534f840e4 100644 --- a/docs/0.62/direct-manipulation/index.html +++ b/docs/0.62/direct-manipulation/index.html @@ -16,7 +16,7 @@ Direct Manipulation · React Native - + @@ -31,7 +31,7 @@
Version: 0.62

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:

setOpacityTo(value) {
// Redacted: animation related code
this.refs[CHILD_REF].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={this._handlePress}>
<View style={styles.button}>
<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:

constructor(props) {
super(props);
this.state = { myButtonOpacity: 1, };
}
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:

  • 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 prop instead.

measureInWindow(callback)

Determines the location of the given view in the window and returns the values via an async callback. If the React root view is embedded in another native view, this will give you the absolute coordinates. If successful, the callback will be called with the following arguments:

  • x
  • y
  • width
  • height

measureLayout(relativeToNativeNode, onSuccess, onFail)

Like measure(), but measures the view relative 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/index.html b/docs/0.62/drawerlayoutandroid/index.html index 34c20c8681d..ee24d8e5e88 100644 --- a/docs/0.62/drawerlayoutandroid/index.html +++ b/docs/0.62/drawerlayoutandroid/index.html @@ -16,7 +16,7 @@ DrawerLayoutAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/easing/index.html index 2f4f831754f..66b4be1800e 100644 --- a/docs/0.62/easing/index.html +++ b/docs/0.62/easing/index.html @@ -16,7 +16,7 @@ Easing · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/environment-setup/index.html index fd2f3f6c23b..169496d85e5 100644 --- a/docs/0.62/environment-setup/index.html +++ b/docs/0.62/environment-setup/index.html @@ -16,7 +16,7 @@ Setting up the development environment · React Native - + @@ -32,7 +32,7 @@
Version: 0.62

Setting up the development environment

This page will help you install and build your first React Native app.

If you are new to mobile development, the easiest way to get started is with Expo CLI. Expo is a set of tools built around React Native and, while it has many features, the most relevant feature for us right now is that it can get you writing a React Native app within minutes. You will only need a recent version of Node.js and a phone or emulator. If you'd like to try out React Native directly in your web browser before installing any tools, you can try out Snack.

If you are already familiar with mobile development, you may want to use React Native CLI. It requires Xcode or Android Studio to get started. If you already have one of these tools installed, you should be able to get up and running within a few minutes. If they are not installed, you should expect to spend about an hour installing and configuring them.

Assuming that you have Node 12 LTS or greater installed, you can use npm to install the Expo CLI command line utility:

npm install -g expo-cli

Then run the following commands to create a new React Native project called "AwesomeProject":

expo init AwesomeProject
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/index.html b/docs/0.62/fast-refresh/index.html index a7bfe04c49c..66f71d6f210 100644 --- a/docs/0.62/fast-refresh/index.html +++ b/docs/0.62/fast-refresh/index.html @@ -16,7 +16,7 @@ Fast Refresh · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/flatlist/index.html index 7a1e7334caa..d6f9f1ace48 100644 --- a/docs/0.62/flatlist/index.html +++ b/docs/0.62/flatlist/index.html @@ -16,7 +16,7 @@ FlatList · React Native - + @@ -31,7 +31,7 @@
Version: 0.62

FlatList

A performant interface for rendering basic, flat lists, supporting the most handy features:

  • Fully cross-platform.
  • Optional horizontal mode.
  • Configurable viewability callbacks.
  • Header support.
  • Footer support.
  • Separator support.
  • Pull to Refresh.
  • Scroll loading.
  • ScrollToIndex support.
  • Multiple column support.

If you need section support, use <SectionList>.

Example

To render multiple columns, use the numColumns prop. Using this approach instead of a flexWrap layout can prevent conflicts with the item height logic.

More complex, multi-select example demonstrating `` usage for perf optimization and avoiding bugs.

  • By passing extraData={selected} to FlatList we make sure FlatList itself will re-render when the state changes. Without setting this prop, FlatList would not know it needs to re-render any items because it is a PureComponent and the prop comparison will not show any changes.
  • keyExtractor tells the list to use the ids for the react keys instead of the default key property.

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, unless it is nested in another FlatList of same orientation.

renderItem

renderItem({ item, index, separators });

Takes an item from data and renders it into the list.

Provides additional metadata like index if you need it, as well as a more generic separators.updateProps function which let you set whatever props you want to change the rendering of either the leading separator or trailing separator in case the more common highlight and unhighlight (which set the highlighted: boolean prop) are insufficient for your use case.

TypeRequired
functionYes
  • item (Object): The item from data being rendered.
  • index (number): The index corresponding to this item in the data array.
  • separators (Object)
    • highlight (Function)
    • unhighlight (Function)
    • updateProps (Function)
      • select (enum('leading', 'trailing'))
      • newProps (Object)

Example usage:

<FlatList
ItemSeparatorComponent={Platform.OS !== 'android' && ({highlighted}) => (
<View style={[style.separator, highlighted && {marginLeft: 0}]} />
)}
data={[{title: 'Title Text', key: 'item1'}]}
renderItem={({item, index, separators}) => (
<TouchableHighlight
key={item.key}
onPress={() => this._onPress(item)}
onShowUnderlay={separators.highlight}
onHideUnderlay={separators.unhighlight}>
<View style={{backgroundColor: 'white'}}>
<Text>{item.title}</Text>
</View>
</TouchableHighlight>
)}
/>

data

For simplicity, data is a plain array. If you want to use something else, like an immutable list, use the underlying VirtualizedList directly.

TypeRequired
arrayYes

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted and leadingItem 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
componentNo

ListEmptyComponent

Rendered when the list is empty. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListFooterComponent

Rendered at the bottom of all the items. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListFooterComponentStyle

Styling for internal View for ListFooterComponent

TypeRequired
style objectNo

ListHeaderComponent

Rendered at the top of all the items. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListHeaderComponentStyle

Styling for internal View for ListHeaderComponent

TypeRequired
style objectNo

columnWrapperStyle

Optional custom style for multi-item rows generated when numColumns > 1.

TypeRequired
style objectNo

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, index) => {length: number, offset: number, index: number}

getItemLayout is an optional optimization that allows skipping the measurement of dynamic content if you know the size (height or width) of items ahead of time. getItemLayout is efficient if you have fixed size items, for example:

getItemLayout={(data, index) => (
{length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index}
)}

Adding getItemLayout can be a great performance boost for lists of several hundred items. Remember to include separator length (height or width) in your offset calculation if you specify ItemSeparatorComponent.

TypeRequired
functionNo

horizontal

If true, renders items next to each other horizontally instead of stacked vertically.

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

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

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 falls back to using the index, like React does.

TypeRequired
functionNo

numColumns

Multiple columns can only be rendered with horizontal={false} and will zig-zag like a flexWrap layout. Items should all be the same height - masonry layouts are not supported.

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

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

onViewableItemsChanged

(info: {
viewableItems: array,
changed: array,
}) => void

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

progressViewOffset

Set this when offset is needed for the loading indicator to show correctly.

TypeRequiredPlatform
numberNoAndroid

legacyImplementation

May not have full feature parity and is meant for debugging and performance comparison.

TypeRequired
booleanNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
booleanNo

removeClippedSubviews

This may improve scroll performance for large lists. On Android the default value is true

Note: May have bugs (missing content) in some circumstances - use at your own risk.

TypeRequired
booleanNo

viewabilityConfig

See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
ViewabilityConfigNo

viewabilityConfig takes a type ViewabilityConfig an object with following properties

PropertyRequiredType
minimumViewTimeNonumber
viewAreaCoveragePercentThresholdNonumber
itemVisiblePercentThresholdNonumber
waitForInteractionNoboolean

At least one of the viewAreaCoveragePercentThreshold or itemVisiblePercentThreshold is required. This needs to be done in the constructor to avoid following error (ref):

Error: Changing viewabilityConfig on the fly is not supported`
constructor (props) {
super(props)
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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.

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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'index' (number) - The index to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position.
  • '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.

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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'item' (object) - The item to scroll to. Required.
  • 'viewPosition' (number)

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'offset' (number) - The offset to scroll to. In case of horizontal being true, the offset is the x-value, in any other case the offset is the y-value. Required.
  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.

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/index.html b/docs/0.62/flexbox/index.html index 5375709cfe7..4eac4ca1eb2 100644 --- a/docs/0.62/flexbox/index.html +++ b/docs/0.62/flexbox/index.html @@ -16,7 +16,7 @@ Layout with Flexbox · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/geolocation/index.html index 2b458499bff..8ba8a259c06 100644 --- a/docs/0.62/geolocation/index.html +++ b/docs/0.62/geolocation/index.html @@ -16,7 +16,7 @@ 🚧 Geolocation · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/gesture-responder-system/index.html index 1321a6fddca..586e344ffb4 100644 --- a/docs/0.62/gesture-responder-system/index.html +++ b/docs/0.62/gesture-responder-system/index.html @@ -16,7 +16,7 @@ Gesture Responder System · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/getting-started/index.html index 2991a40ea0c..6482ecd6394 100644 --- a/docs/0.62/getting-started/index.html +++ b/docs/0.62/getting-started/index.html @@ -16,7 +16,7 @@ Introduction · React Native - + @@ -30,7 +30,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.58., 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/index.html b/docs/0.62/handling-text-input/index.html index c6bb28b8996..3b3c35d39fa 100644 --- a/docs/0.62/handling-text-input/index.html +++ b/docs/0.62/handling-text-input/index.html @@ -16,7 +16,7 @@ Handling Text Input · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/handling-touches/index.html index d29775f1e2b..a05a94179e0 100644 --- a/docs/0.62/handling-touches/index.html +++ b/docs/0.62/handling-touches/index.html @@ -16,7 +16,7 @@ Handling Touches · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/headless-js-android/index.html index 41c38775eda..caf187dbf34 100644 --- a/docs/0.62/headless-js-android/index.html +++ b/docs/0.62/headless-js-android/index.html @@ -16,7 +16,7 @@ Headless JS · React Native - + @@ -41,7 +41,7 @@
}
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 dc4d46121a3..5044343c46e 100644 --- a/docs/0.62/height-and-width/index.html +++ b/docs/0.62/height-and-width/index.html @@ -16,7 +16,7 @@ Height and Width · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/hermes/index.html index e6b410ef952..0cd0064eaa8 100644 --- a/docs/0.62/hermes/index.html +++ b/docs/0.62/hermes/index.html @@ -16,7 +16,7 @@ Using Hermes · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/image-style-props/index.html index 19e1a30a8c5..18c3e788e11 100644 --- a/docs/0.62/image-style-props/index.html +++ b/docs/0.62/image-style-props/index.html @@ -16,7 +16,7 @@ Image Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/image/index.html index 4a2b49986fd..16cc1edfc51 100644 --- a/docs/0.62/image/index.html +++ b/docs/0.62/image/index.html @@ -16,7 +16,7 @@ Image · React Native - + @@ -33,7 +33,7 @@
// For WebP support, including animated WebP
implementation 'com.facebook.fresco:animated-webp:2.1.0'
implementation 'com.facebook.fresco:webpsupport:2.0.0'
// 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

  • Layout Props...

  • Shadow Props...

  • Transforms...

  • borderTopRightRadius: number

  • backfaceVisibility: enum('visible', 'hidden')

  • borderBottomLeftRadius: number

  • borderBottomRightRadius: number

  • borderColor: color

  • borderRadius: number

  • borderTopLeftRadius: number

  • backgroundColor: color

  • borderWidth: number

  • opacity: number

  • overflow: enum('visible', 'hidden')

  • resizeMode: Object.keys(ImageResizeMode)

  • tintColor: color

    Changes the color of all the non-transparent pixels to the tintColor.

  • overlayColor: string (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 http://frescolib.org/docs/rounded-corners-and-circles.html

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}:

  • 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 (which should be wrapped in the require('./path/to/image.png') function).
  • width, height - can be specified if known at build time, in which case these will be used to set the default <Image/> component dimensions.
  • scale - used 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.

If passing a number:

  • number - Opaque type returned by something like require('./image.jpg').

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.

  • auto: Use heuristics to pick between resize and scale.

  • resize: A software operation which changes the encoded image in memory before it gets decoded. This should be used instead of scale when the image is much larger than the view.

  • scale: The image gets drawn downscaled or upscaled. Compared to resize, scale is faster (usually hardware accelerated) and produces higher quality images. This should be used if the image is smaller than the view. It should also be used if the image is slightly bigger than the view.

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.

  • cover: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or larger than the corresponding dimension of the view (minus padding).

  • contain: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or less than the corresponding dimension of the view (minus padding).

  • stretch: Scale width and height independently, This may change the aspect ratio of the src.

  • repeat: Repeat the image to cover the frame of the view. The image will keep its size and aspect ratio, unless it is larger than the view, in which case it will be scaled down uniformly so that it is contained in the view.

  • center: Center the image in the view along both dimensions. If the image is larger than the view, scale it down uniformly so that it is contained in the view.

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/index.html b/docs/0.62/imagebackground/index.html index 4906c958529..f882877fce8 100644 --- a/docs/0.62/imagebackground/index.html +++ b/docs/0.62/imagebackground/index.html @@ -16,7 +16,7 @@ ImageBackground · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/imageeditor/index.html index e464cb56956..6f528d9b019 100644 --- a/docs/0.62/imageeditor/index.html +++ b/docs/0.62/imageeditor/index.html @@ -16,7 +16,7 @@ 🚧 ImageEditor · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/imagepickerios/index.html index 0180dcb167a..ce97d3081d5 100644 --- a/docs/0.62/imagepickerios/index.html +++ b/docs/0.62/imagepickerios/index.html @@ -16,7 +16,7 @@ 🚧 ImagePickerIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/images/index.html index c9a002807e0..4e1af48c65d 100644 --- a/docs/0.62/images/index.html +++ b/docs/0.62/images/index.html @@ -16,7 +16,7 @@ Images · React Native - + @@ -33,7 +33,7 @@
// GOOD
var icon = this.props.active
? require('./my-icon-active.png')
: require('./my-icon-inactive.png');
<Image source={icon} />;

Note that image sources required this way include size (width, height) info for the Image. If you need to scale the image dynamically (i.e. via flex), you may need to manually set { width: undefined, height: undefined } on the style attribute.

Static Non-Image Resources

The require syntax described above can be used to statically include audio, video or document files in your project as well. Most common file types are supported including .mp3, .wav, .mp4, .mov, .html and .pdf. See bundler defaults for the full list.

You can add support for other types by adding an assetExts resolver option in your Metro configuration.

A caveat is that videos must use absolute positioning instead of flexGrow, since size info is not currently passed for non-image assets. This limitation doesn't occur for videos that are linked directly into Xcode or the Assets folder for Android.

Images From Hybrid App's Resources

If you are building a hybrid app (some UIs in React Native, some UIs in platform code) you can still use images that are already bundled into the app.

For images included via Xcode asset catalogs or in the Android drawable folder, use the image name without the extension:

<Image
source={{ uri: 'app_icon' }}
style={{ width: 40, height: 40 }}
/>

For images in the Android assets folder, use the asset:/ scheme:

<Image
source={{ uri: 'asset:/app_icon.png' }}
style={{ width: 40, height: 40 }}
/>

These approaches provide no safety checks. It's up to you to guarantee that those images are available in the application. Also you have to specify image dimensions manually.

Network Images

Many of the images you will display in your app will not be available at compile time, or you will want to load some dynamically to keep the binary size down. Unlike with static resources, you will need to manually specify the dimensions of your image. It's highly recommended that you use https as well in order to satisfy App Transport Security requirements on iOS.

// GOOD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}}
style={{width: 400, height: 400}} />
// 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.

  • default: Use the native platforms default strategy.
  • reload: The data for the URL will be loaded from the originating source. No existing cache data should be used to satisfy a URL load request.
  • force-cache: The existing cached data will be used to satisfy the request, regardless of its age or expiration date. If there is no existing data in the cache corresponding the request, the data is loaded from the originating source.
  • only-if-cached: The existing cache data will be used to satisfy a request, regardless of its age or expiration date. If there is no existing data in the cache corresponding to a URL load request, no attempt is made to load the data from the originating source, and the load is considered to have failed.
<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:

  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomLeftRadius
  • borderBottomRightRadius

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/index.html b/docs/0.62/imagestore/index.html index f49bdcc2185..71c683f860d 100644 --- a/docs/0.62/imagestore/index.html +++ b/docs/0.62/imagestore/index.html @@ -16,7 +16,7 @@ ImageStore · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/improvingux/index.html index 9562e8b160b..d5cd9ffbf8f 100644 --- a/docs/0.62/improvingux/index.html +++ b/docs/0.62/improvingux/index.html @@ -16,7 +16,7 @@ Improving User Experience · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/inputaccessoryview/index.html index b63ca92642f..5d9c1279f02 100644 --- a/docs/0.62/inputaccessoryview/index.html +++ b/docs/0.62/inputaccessoryview/index.html @@ -16,7 +16,7 @@ InputAccessoryView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/integration-with-existing-apps/index.html index 994a9a0ec97..342dcb9f921 100644 --- a/docs/0.62/integration-with-existing-apps/index.html +++ b/docs/0.62/integration-with-existing-apps/index.html @@ -16,7 +16,7 @@ Integration with Existing Apps · React Native - + @@ -45,7 +45,7 @@
@Override
protected void onDestroy() {
super.onDestroy();
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/index.html b/docs/0.62/interactionmanager/index.html index d48588f5998..c60fbc9ff72 100644 --- a/docs/0.62/interactionmanager/index.html +++ b/docs/0.62/interactionmanager/index.html @@ -16,7 +16,7 @@ InteractionManager · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/intro-react-native-components/index.html index ad58ef6036c..87e3a248cf0 100644 --- a/docs/0.62/intro-react-native-components/index.html +++ b/docs/0.62/intro-react-native-components/index.html @@ -16,7 +16,7 @@ Core Components and Native Components · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/intro-react/index.html index 3f8f23c2ec2..39eebbec8af 100644 --- a/docs/0.62/intro-react/index.html +++ b/docs/0.62/intro-react/index.html @@ -16,7 +16,7 @@ React Fundamentals · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/javascript-environment/index.html index a160fc6c882..75119a705f2 100644 --- a/docs/0.62/javascript-environment/index.html +++ b/docs/0.62/javascript-environment/index.html @@ -16,7 +16,7 @@ JavaScript Environment · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/keyboard/index.html index 0e345bc926d..5415d891926 100644 --- a/docs/0.62/keyboard/index.html +++ b/docs/0.62/keyboard/index.html @@ -16,7 +16,7 @@ Keyboard · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/keyboardavoidingview/index.html index 8668fdde5b9..cb88ee6b457 100644 --- a/docs/0.62/keyboardavoidingview/index.html +++ b/docs/0.62/keyboardavoidingview/index.html @@ -16,7 +16,7 @@ KeyboardAvoidingView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/layout-props/index.html index 9e3d6de1a17..a0e35fc11c4 100644 --- a/docs/0.62/layout-props/index.html +++ b/docs/0.62/layout-props/index.html @@ -16,7 +16,7 @@ Layout Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/layoutanimation/index.html index 45ce772f6a2..4539547439d 100644 --- a/docs/0.62/layoutanimation/index.html +++ b/docs/0.62/layoutanimation/index.html @@ -16,7 +16,7 @@ LayoutAnimation · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/libraries/index.html index f63f6f4a360..39c673c6e87 100644 --- a/docs/0.62/libraries/index.html +++ b/docs/0.62/libraries/index.html @@ -16,7 +16,7 @@ Using Libraries · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/linking-libraries-ios/index.html index 199fec630c5..ac08880e0fb 100644 --- a/docs/0.62/linking-libraries-ios/index.html +++ b/docs/0.62/linking-libraries-ios/index.html @@ -16,7 +16,7 @@ Linking Libraries · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/linking/index.html index 4baa6b94527..a25abaf01c3 100644 --- a/docs/0.62/linking/index.html +++ b/docs/0.62/linking/index.html @@ -16,7 +16,7 @@ Linking · React Native - + @@ -30,7 +30,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(url) -- 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/index.html b/docs/0.62/listview/index.html index 857acea4d79..b5d6d4c7300 100644 --- a/docs/0.62/listview/index.html +++ b/docs/0.62/listview/index.html @@ -16,7 +16,7 @@ ListView · React Native - + @@ -31,7 +31,7 @@
Version: 0.62

ListView

DEPRECATED - use one of the new list components, such as FlatList or SectionList for bounded memory use, fewer bugs, better performance, an easier to use API, and more features. Check out this blog post for more details.

ListView - A core component designed for efficient display of vertically scrolling lists of changing data. The minimal API is to create a ListView.DataSource, populate it with a flat array of data blobs, and instantiate a ListView component with that data source and a renderRow callback which takes a blob from the data array and returns a renderable component.

Minimal example:

class MyComponent extends Component {
constructor() {
super();
const ds = new ListView.DataSource({
rowHasChanged: (r1, r2) => r1 !== r2
});
this.state = {
dataSource: ds.cloneWithRows(['row 1', 'row 2'])
};
}
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:

  • Only re-render changed rows - the rowHasChanged function provided to the data source tells the ListView if it needs to re-render a row because the source data has changed - see ListViewDataSource for more details.

  • Rate-limited row rendering - By default, only one row is rendered per event-loop (customizable with the pageSize prop). This breaks up the work into smaller chunks to reduce the chance of dropping frames while rendering rows.

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/index.html b/docs/0.62/listviewdatasource/index.html index d2ecc536222..b5538d13ba2 100644 --- a/docs/0.62/listviewdatasource/index.html +++ b/docs/0.62/listviewdatasource/index.html @@ -16,7 +16,7 @@ ListViewDataSource · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/maskedviewios/index.html index ddbcca2ded7..0902ac5e18e 100644 --- a/docs/0.62/maskedviewios/index.html +++ b/docs/0.62/maskedviewios/index.html @@ -16,7 +16,7 @@ 🚧 MaskedViewIOS · React Native - + @@ -31,7 +31,7 @@
Version: 0.62

🚧 MaskedViewIOS

Deprecated. Use @react-native-community/masked-view instead.

Renders the child view with a mask specified in the maskElement prop.

Example

import React from 'react';
import { MaskedViewIOS, Text, View } from 'react-native';
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/index.html b/docs/0.62/modal/index.html index 1432fbff7f2..9a3a17d4f8b 100644 --- a/docs/0.62/modal/index.html +++ b/docs/0.62/modal/index.html @@ -16,7 +16,7 @@ Modal · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/more-resources/index.html index 6c43e806cd1..b175dd23294 100644 --- a/docs/0.62/more-resources/index.html +++ b/docs/0.62/more-resources/index.html @@ -16,7 +16,7 @@ More Resources · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/native-components-android/index.html index bd38c42010d..bcf43b44234 100644 --- a/docs/0.62/native-components-android/index.html +++ b/docs/0.62/native-components-android/index.html @@ -16,7 +16,7 @@ Native UI Components · React Native - + @@ -40,7 +40,7 @@
class MyCustomView extends React.Component {
constructor(props) {
super(props);
this._onChange = this._onChange.bind(this);
}
_onChange(event: Event) {
if (!this.props.onChangeMessage) {
return;
}
this.props.onChangeMessage(event.nativeEvent.message);
}
render() {
return <RCTMyCustomView {...this.props} onChange={this._onChange} />;
}
}
MyCustomView.propTypes = {
/**
* Callback that is called continuously when the user is dragging the map.
*/
onChangeMessage: PropTypes.func,
...
};
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
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 3b11070deb4..8e8178c80c7 100644 --- a/docs/0.62/native-components-ios/index.html +++ b/docs/0.62/native-components-ios/index.html @@ -16,7 +16,7 @@ Native UI Components · React Native - + @@ -93,7 +93,7 @@
- (NSDictionary *)constantsToExport
{
UIDatePicker *dp = [[UIDatePicker alloc] init];
[dp layoutIfNeeded];
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/index.html b/docs/0.62/native-modules-android/index.html index 702572cf8e8..44a8d20c62d 100644 --- a/docs/0.62/native-modules-android/index.html +++ b/docs/0.62/native-modules-android/index.html @@ -16,7 +16,7 @@ Native Modules · React Native - + @@ -81,7 +81,7 @@
@Override
public void onHostPause() {
// Activity `onPause`
}
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}
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 1f1f5de9b9f..df337c42839 100644 --- a/docs/0.62/native-modules-ios/index.html +++ b/docs/0.62/native-modules-ios/index.html @@ -16,7 +16,7 @@ Native Modules · React Native - + @@ -68,7 +68,7 @@
RCT_EXTERN_METHOD(addEvent:(NSString *)name location:(NSString *)location date:(nonnull NSNumber *)date)
@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/index.html b/docs/0.62/native-modules-setup/index.html index 2341984b83f..7d49b2442cb 100644 --- a/docs/0.62/native-modules-setup/index.html +++ b/docs/0.62/native-modules-setup/index.html @@ -16,7 +16,7 @@ Native Modules Setup · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/navigation/index.html index 62bc2782e3b..4d2f24d5a92 100644 --- a/docs/0.62/navigation/index.html +++ b/docs/0.62/navigation/index.html @@ -16,7 +16,7 @@ Navigating Between Screens · React Native - + @@ -33,7 +33,7 @@
const Stack = createStackNavigator();
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/index.html b/docs/0.62/netinfo/index.html index dd801b79db9..7380656aafe 100644 --- a/docs/0.62/netinfo/index.html +++ b/docs/0.62/netinfo/index.html @@ -16,7 +16,7 @@ NetInfo · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/network/index.html index 9fa8e928b2f..fdce64f4083 100644 --- a/docs/0.62/network/index.html +++ b/docs/0.62/network/index.html @@ -16,7 +16,7 @@ Networking · React Native - + @@ -36,7 +36,7 @@
ws.onerror = (e) => {
// an error occurred
console.log(e.message);
};
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

  • redirect:manual
  • credentials:omit
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 57747c5f2ac..9d83fab74af 100644 --- a/docs/0.62/optimizing-flatlist-configuration/index.html +++ b/docs/0.62/optimizing-flatlist-configuration/index.html @@ -16,7 +16,7 @@ Optimizing Flatlist Configuration · React Native - + @@ -33,7 +33,7 @@
<FlatList
data={items}
renderItem={renderItem}
/>
// ...
}
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 fa482dffa00..955e2a0991d 100644 --- a/docs/0.62/out-of-tree-platforms/index.html +++ b/docs/0.62/out-of-tree-platforms/index.html @@ -16,7 +16,7 @@ Out-of-Tree Platforms · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/panresponder/index.html index 2a5e2fa8ce0..bdede34dd2d 100644 --- a/docs/0.62/panresponder/index.html +++ b/docs/0.62/panresponder/index.html @@ -16,7 +16,7 @@ PanResponder · React Native - + @@ -32,7 +32,7 @@
onPanResponderGrant: (evt, gestureState) => {
// The gesture has started. Show visual feedback so the user knows
// what is happening!
// gestureState.d{x,y} will be set to zero now
},
onPanResponderMove: (evt, gestureState) => {
// The most recent move distance is gestureState.move{X,Y}
// The accumulated gesture distance since becoming responder is
// gestureState.d{x,y}
},
onPanResponderTerminationRequest: (evt, gestureState) =>
true,
onPanResponderRelease: (evt, gestureState) => {
// The user has released all touches while this view is the
// responder. This typically means a gesture has succeeded
},
onPanResponderTerminate: (evt, gestureState) => {
// Another component has become the responder, so this gesture
// should be cancelled
},
onShouldBlockNativeResponder: (evt, gestureState) => {
// Returns whether this component should block native components from becoming the JS
// responder. Returns true by default. Is currently only supported on android.
return true;
}
})
).current;
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:

  • onMoveShouldSetPanResponder: (e, gestureState) => {...}
  • onMoveShouldSetPanResponderCapture: (e, gestureState) => {...}
  • onStartShouldSetPanResponder: (e, gestureState) => {...}
  • onStartShouldSetPanResponderCapture: (e, gestureState) => {...}
  • onPanResponderReject: (e, gestureState) => {...}
  • onPanResponderGrant: (e, gestureState) => {...}
  • onPanResponderStart: (e, gestureState) => {...}
  • onPanResponderEnd: (e, gestureState) => {...}
  • onPanResponderRelease: (e, gestureState) => {...}
  • onPanResponderMove: (e, gestureState) => {...}
  • onPanResponderTerminate: (e, gestureState) => {...}
  • onPanResponderTerminationRequest: (e, gestureState) => {...}
  • onShouldBlockNativeResponder: (e, gestureState) => {...}

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/index.html b/docs/0.62/performance/index.html index 4d67fe2dd0f..68a99d4b0cd 100644 --- a/docs/0.62/performance/index.html +++ b/docs/0.62/performance/index.html @@ -16,7 +16,7 @@ Performance Overview · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/permissionsandroid/index.html index 00676153ddd..4b38a92354a 100644 --- a/docs/0.62/permissionsandroid/index.html +++ b/docs/0.62/permissionsandroid/index.html @@ -16,7 +16,7 @@ PermissionsAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/picker-item/index.html index cb3a49aeee5..9c24828e671 100644 --- a/docs/0.62/picker-item/index.html +++ b/docs/0.62/picker-item/index.html @@ -16,7 +16,7 @@ Picker.Item · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/picker-style-props/index.html index 684bac93075..ff42d566aa0 100644 --- a/docs/0.62/picker-style-props/index.html +++ b/docs/0.62/picker-style-props/index.html @@ -16,7 +16,7 @@ Picker Style Props · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.62/picker/index.html b/docs/0.62/picker/index.html index e827d8a44db..3a12956c8f6 100644 --- a/docs/0.62/picker/index.html +++ b/docs/0.62/picker/index.html @@ -16,7 +16,7 @@ 🚧 Picker · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/pickerios/index.html index 030f870ecbb..dddd7cd337b 100644 --- a/docs/0.62/pickerios/index.html +++ b/docs/0.62/pickerios/index.html @@ -16,7 +16,7 @@ 🚧 PickerIOS · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.62/pixelratio/index.html b/docs/0.62/pixelratio/index.html index 33efa453b9f..ed331a20e7b 100644 --- a/docs/0.62/pixelratio/index.html +++ b/docs/0.62/pixelratio/index.html @@ -16,7 +16,7 @@ PixelRatio · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/platform-specific-code/index.html index b0c8b16acee..94afdbc0e85 100644 --- a/docs/0.62/platform-specific-code/index.html +++ b/docs/0.62/platform-specific-code/index.html @@ -16,7 +16,7 @@ Platform Specific Code · React Native - + @@ -36,7 +36,7 @@
if (Platform.Version === 25) {
console.log('Running on Nougat!');
}

Detecting the iOS version

On iOS, the Version is a result of -[UIDevice systemVersion], which is a string with the current version of the operating system. An example of the system version is "10.3". For example, to detect the major version number on iOS:

import { Platform } from 'react-native';
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/index.html b/docs/0.62/profiling/index.html index bf2847686d7..0676b5e280e 100644 --- a/docs/0.62/profiling/index.html +++ b/docs/0.62/profiling/index.html @@ -16,7 +16,7 @@ Profiling · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/progressbarandroid/index.html index 1f9115b43b4..7ded8906f72 100644 --- a/docs/0.62/progressbarandroid/index.html +++ b/docs/0.62/progressbarandroid/index.html @@ -16,7 +16,7 @@ 🚧 ProgressBarAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/progressviewios/index.html index 74eb33d843e..0350d98fd63 100644 --- a/docs/0.62/progressviewios/index.html +++ b/docs/0.62/progressviewios/index.html @@ -16,7 +16,7 @@ 🚧 ProgressViewIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/props/index.html index 947856618f9..8547f5a9061 100644 --- a/docs/0.62/props/index.html +++ b/docs/0.62/props/index.html @@ -16,7 +16,7 @@ Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/publishing-forks/index.html index 4f55ced2f38..c9619f40391 100644 --- a/docs/0.62/publishing-forks/index.html +++ b/docs/0.62/publishing-forks/index.html @@ -16,7 +16,7 @@ Publish your own version of react native · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/publishing-to-app-store/index.html index e3ad6c4194b..bbe97c32e12 100644 --- a/docs/0.62/publishing-to-app-store/index.html +++ b/docs/0.62/publishing-to-app-store/index.html @@ -16,7 +16,7 @@ Publishing to Apple App Store · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/pushnotificationios/index.html index e9c955c4427..11755aead2e 100644 --- a/docs/0.62/pushnotificationios/index.html +++ b/docs/0.62/pushnotificationios/index.html @@ -16,7 +16,7 @@ 🚧 PushNotificationIOS · React Native - + @@ -32,7 +32,7 @@
return YES;
}
//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:

  • alertBody : The message displayed in the notification alert.
  • alertAction : The "action" displayed beneath an actionable notification. Defaults to "view". Note that Apple no longer shows this in iOS 10 +
  • alertTitle : The text displayed as the title of the notification alert.
  • soundName : The sound played when the notification is fired (optional).
  • isSilent : If true, the notification will appear without sound (optional).
  • category : The category of this notification, required for actionable notifications (optional).
  • userInfo : An object containing additional notification data (optional).
  • applicationIconBadgeNumber The number to display as the app's icon badge. The default value of this property is 0, which means that no badge is displayed (optional).

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

  • fireDate : The date and time when the system should deliver the notification.
  • alertTitle : The text displayed as the title of the notification alert.
  • alertBody : The message displayed in the notification alert.
  • alertAction : The "action" displayed beneath an actionable notification. Defaults to "view". Note that Apple no longer shows this in iOS 10 +
  • soundName : The sound played when the notification is fired (optional).
  • isSilent : If true, the notification will appear without sound (optional).
  • category : The category of this notification, required for actionable notifications (optional).
  • userInfo : An object containing additional notification data (optional).
  • applicationIconBadgeNumber The number to display as the app's icon badge. Setting the number to 0 removes the icon badge (optional).
  • repeatInterval : The interval to repeat as a string. Possible values: minute, hour, day, week, month, year (optional).

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:

  • identifier : The identifier of this notification.
  • title : The title of this notification.
  • body : The body of this notification.
  • category : The category of this notification (optional).
  • userInfo : An object containing additional notification data (optional).
  • thread-id : The thread identifier of this notification, if has one.

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:

  • notification : Fired when a remote notification is received. The handler will be invoked with an instance of PushNotificationIOS.
  • localNotification : Fired when a local notification is received. The handler will be invoked with an instance of PushNotificationIOS.
  • register: Fired when the user registers for remote notifications. The handler will be invoked with a hex string representing the deviceToken.
  • registrationError: Fired when the user fails to register for remote notifications. Typically occurs when APNS is having issues, or the device is a simulator. The handler will be invoked with {message: string, code: number, details: any}.

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:

  • alert
  • badge
  • sound

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:

  • alert :boolean
  • badge :boolean
  • sound :boolean

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/index.html b/docs/0.62/ram-bundles-inline-requires/index.html index 8083353ef17..8b26c7c5a12 100644 --- a/docs/0.62/ram-bundles-inline-requires/index.html +++ b/docs/0.62/ram-bundles-inline-requires/index.html @@ -16,7 +16,7 @@ RAM Bundles and Inline Requires · React Native - + @@ -42,7 +42,7 @@
const config = {
transformer: {
getTransformOptions: () => {
const moduleMap = {};
modulePaths.forEach((path) => {
if (fs.existsSync(path)) {
moduleMap[resolve(path)] = true;
}
});
return {
preloadedModules: moduleMap,
transform: { inlineRequires: { blacklist: moduleMap } }
};
}
},
projectRoot: ROOT_FOLDER
};
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/index.html b/docs/0.62/react-node/index.html index 8946d7fe9f4..2eabd6a5c82 100644 --- a/docs/0.62/react-node/index.html +++ b/docs/0.62/react-node/index.html @@ -16,7 +16,7 @@ React Node Object Type · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/refreshcontrol/index.html index 675560e7699..178c5e99830 100644 --- a/docs/0.62/refreshcontrol/index.html +++ b/docs/0.62/refreshcontrol/index.html @@ -16,7 +16,7 @@ RefreshControl · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/removing-default-permissions/index.html index 9fd9ef20984..eaa28460c2e 100644 --- a/docs/0.62/removing-default-permissions/index.html +++ b/docs/0.62/removing-default-permissions/index.html @@ -16,7 +16,7 @@ Removing Default Permissions · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/running-on-device/index.html index 2365872111c..bc405f434ed 100644 --- a/docs/0.62/running-on-device/index.html +++ b/docs/0.62/running-on-device/index.html @@ -16,7 +16,7 @@ Running On Device · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/running-on-simulator-ios/index.html index 6b6c5b5675f..c50fcf41a96 100644 --- a/docs/0.62/running-on-simulator-ios/index.html +++ b/docs/0.62/running-on-simulator-ios/index.html @@ -16,7 +16,7 @@ Running On Simulator · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/safeareaview/index.html index 10ee7c83cd5..8321f2dc480 100644 --- a/docs/0.62/safeareaview/index.html +++ b/docs/0.62/safeareaview/index.html @@ -16,7 +16,7 @@ SafeAreaView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/scrollview/index.html index 3ac3d2ec8d3..50808d0e269 100644 --- a/docs/0.62/scrollview/index.html +++ b/docs/0.62/scrollview/index.html @@ -16,7 +16,7 @@ ScrollView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/sectionlist/index.html index 4b792d7a6ea..e99db8a5715 100644 --- a/docs/0.62/sectionlist/index.html +++ b/docs/0.62/sectionlist/index.html @@ -16,7 +16,7 @@ SectionList · React Native - + @@ -30,7 +30,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, function, 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 Class, a render function, or a rendered element.

TypeRequired
[component, function, element]No

ListFooterComponent

Rendered at the very end of the list. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
[component, function, element]No

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, 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, function, 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/index.html b/docs/0.62/security/index.html index 23ac9b49d6e..d1b25a85ae8 100644 --- a/docs/0.62/security/index.html +++ b/docs/0.62/security/index.html @@ -16,7 +16,7 @@ Security · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/segmentedcontrolios/index.html index aa4fe7c25ab..9f2d5e8a17c 100644 --- a/docs/0.62/segmentedcontrolios/index.html +++ b/docs/0.62/segmentedcontrolios/index.html @@ -16,7 +16,7 @@ 🚧 SegmentedControlIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/settings/index.html index e20350afee1..77dcbf2c7f9 100644 --- a/docs/0.62/settings/index.html +++ b/docs/0.62/settings/index.html @@ -16,7 +16,7 @@ Settings · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/shadow-props/index.html index 30b7fc09f4c..2890f64b4bb 100644 --- a/docs/0.62/shadow-props/index.html +++ b/docs/0.62/shadow-props/index.html @@ -16,7 +16,7 @@ Shadow Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/share/index.html index 60e79e88dda..d4ef053271a 100644 --- a/docs/0.62/share/index.html +++ b/docs/0.62/share/index.html @@ -16,7 +16,7 @@ Share · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/signed-apk-android/index.html index cab26843064..d46ce2a4a00 100644 --- a/docs/0.62/signed-apk-android/index.html +++ b/docs/0.62/signed-apk-android/index.html @@ -16,7 +16,7 @@ Publishing to Google Play Store · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/slider/index.html index fbaaeac3c77..30d4ac016a2 100644 --- a/docs/0.62/slider/index.html +++ b/docs/0.62/slider/index.html @@ -16,7 +16,7 @@ 🚧 Slider · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/snapshotviewios/index.html index d461c2d1ec1..97797e4b04c 100644 --- a/docs/0.62/snapshotviewios/index.html +++ b/docs/0.62/snapshotviewios/index.html @@ -16,7 +16,7 @@ SnapshotViewIOS · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.62/state/index.html b/docs/0.62/state/index.html index 2a8717e8ec6..aa7289dad00 100644 --- a/docs/0.62/state/index.html +++ b/docs/0.62/state/index.html @@ -16,7 +16,7 @@ State · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/statusbar/index.html index 68780363c01..e03a3240990 100644 --- a/docs/0.62/statusbar/index.html +++ b/docs/0.62/statusbar/index.html @@ -16,7 +16,7 @@ StatusBar · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/statusbarios/index.html index edea7b04b9c..4d972ea866c 100644 --- a/docs/0.62/statusbarios/index.html +++ b/docs/0.62/statusbarios/index.html @@ -16,7 +16,7 @@ 🚧 StatusBarIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/style/index.html index f286c0d73f6..c6fbcb6bb3a 100644 --- a/docs/0.62/style/index.html +++ b/docs/0.62/style/index.html @@ -16,7 +16,7 @@ Style · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/stylesheet/index.html index a07115dfbd8..9be9e6a72e6 100644 --- a/docs/0.62/stylesheet/index.html +++ b/docs/0.62/stylesheet/index.html @@ -16,7 +16,7 @@ StyleSheet · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/switch/index.html index 179c84f7c29..491058f8c5a 100644 --- a/docs/0.62/switch/index.html +++ b/docs/0.62/switch/index.html @@ -16,7 +16,7 @@ Switch · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/symbolication/index.html index de916cf2ffd..aa3c9dcac3b 100644 --- a/docs/0.62/symbolication/index.html +++ b/docs/0.62/symbolication/index.html @@ -16,7 +16,7 @@ Symbolicating a stack trace · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/systrace/index.html index 3f76dd21cbb..5ff8d0f67fd 100644 --- a/docs/0.62/systrace/index.html +++ b/docs/0.62/systrace/index.html @@ -16,7 +16,7 @@ Systrace · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/tabbarios-item/index.html index 6ec2c4310c4..73e401f27c2 100644 --- a/docs/0.62/tabbarios-item/index.html +++ b/docs/0.62/tabbarios-item/index.html @@ -16,7 +16,7 @@ TabBarIOS.Item · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/tabbarios/index.html index 93ebf2f3fd9..a0ad4ec9aeb 100644 --- a/docs/0.62/tabbarios/index.html +++ b/docs/0.62/tabbarios/index.html @@ -16,7 +16,7 @@ TabBarIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/testing-overview/index.html index 4d6cce52459..c4936e06e20 100644 --- a/docs/0.62/testing-overview/index.html +++ b/docs/0.62/testing-overview/index.html @@ -16,7 +16,7 @@ Testing · React Native - + @@ -34,7 +34,7 @@
fireEvent.changeText(
getByPlaceholder('Enter grocery item'),
'banana'
);
fireEvent.press(getByText('Add the item to list'));
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:

  • For you as a developer or reviewer, it can be hard to tell whether a change in snapshot is intended or whether it's evidence of a bug. Especially large snapshots can quickly become hard to understand and their added value becomes low.
  • When snapshot is created, at that point it is considered to be correct-even in the case when the rendered output is actually wrong.
  • When a snapshot fails, it's tempting to update it using the --updateSnapshot jest option without taking proper care to investigate whether the change is expected. Certain developer discipline is thus needed.

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:

  • writing them is more time consuming compared to the other types of tests
  • they can be slower to run
  • they are more prone to flakiness (a "flaky" test is a test which randomly passes and fails without any change to code)

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/index.html b/docs/0.62/text-style-props/index.html index 1871a82d859..4745106ec16 100644 --- a/docs/0.62/text-style-props/index.html +++ b/docs/0.62/text-style-props/index.html @@ -16,7 +16,7 @@ Text Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/text/index.html index 2eb99a63c12..dbb91f5a590 100644 --- a/docs/0.62/text/index.html +++ b/docs/0.62/text/index.html @@ -16,7 +16,7 @@ Text · React Native - + @@ -34,7 +34,7 @@
// otherwise, the text will flow in its own block
// |First part |
// |and |
// |second part|

Limited Style Inheritance

On the web, the usual way to set a font family and size for the entire document is to take advantage of inherited CSS properties like so:

html {
font-family: 'lucida grande', tahoma, verdana, arial, sans-serif;
font-size: 11px;
color: #141823;
}

All elements in the document will inherit this font unless they or one of their parents specifies a new rule.

In React Native, we are more strict about it: you must wrap all the text nodes inside of a <Text> component. You cannot have a text node directly under a <View>.

// BAD: will raise exception, can't have a text node as child of a <View>
<View>
Some text
</View>
// 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:

  • (Developer) React components are designed with strong isolation in mind: You should be able to drop a component anywhere in your application, trusting that as long as the props are the same, it will look and behave the same way. Text properties that could inherit from outside of the props would break this isolation.

  • (Implementor) The implementation of React Native is also simplified. We do not need to have a fontFamily field on every single element, and we do not need to potentially traverse the tree up to the root every time we display a text node. The style inheritance is only encoded inside of the native Text component and doesn't leak to other components or the system itself.

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:

  • 'none' - The element has no role.
  • 'button' - The element should be treated as a button.
  • 'link' - The element should be treated as a link.
  • 'header' - The element is a header that divides content into sections.
  • 'search' - The element should be treated as a search field.
  • 'image' - The element should be treated as an image.
  • 'key' - The element should be treated like a keyboard key.
  • 'text' - The element should be treated as text.
  • 'summary' - The element provides app summary information.
  • 'imagebutton' - The element has the role of both an image and also a button.
  • 'adjustable' - The element allows adjustment over a range of values.

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:

  • 'selected' - The element is in a selected state.
  • 'disabled' - The element is in a disabled state.
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.

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:

  • 'phoneNumber'
  • 'link'
  • 'email'
  • 'none'
  • 'all'
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:

  • head - The line is displayed so that the end fits in the container and the missing text at the beginning of the line is indicated by an ellipsis glyph. e.g., "...wxyz"
  • middle - The line is displayed so that the beginning and end fit in the container and the missing text in the middle is indicated by an ellipsis glyph. "ab...yz"
  • tail - The line is displayed so that the beginning fits in the container and the missing text at the end of the line is indicated by an ellipsis glyph. e.g., "abcd..."
  • clip - Lines are not drawn past the edge of the text container.

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:

  • 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

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
  • TextLayoutEvent - SyntheticEvent object that contains a key called lines with a value which is an array containing objects with the following properties
    • { x: number, y: number, width: number, height: number, ascender: number, capHeight: number, descender: number, text: string, xHeight: number,}

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/index.html b/docs/0.62/textinput/index.html index 49f0feebff0..3c9c3e4e013 100644 --- a/docs/0.62/textinput/index.html +++ b/docs/0.62/textinput/index.html @@ -16,7 +16,7 @@ TextInput · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/timepickerandroid/index.html index e919bb58f9a..ed72d40dcfb 100644 --- a/docs/0.62/timepickerandroid/index.html +++ b/docs/0.62/timepickerandroid/index.html @@ -16,7 +16,7 @@ 🚧 TimePickerAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/timers/index.html index a83022561aa..f61cf9826ee 100644 --- a/docs/0.62/timers/index.html +++ b/docs/0.62/timers/index.html @@ -16,7 +16,7 @@ Timers · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/toastandroid/index.html index 2998ff42f15..c2a0f437bd1 100644 --- a/docs/0.62/toastandroid/index.html +++ b/docs/0.62/toastandroid/index.html @@ -16,7 +16,7 @@ ToastAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/toolbarandroid/index.html index 3c875247c57..91412b8ef3b 100644 --- a/docs/0.62/toolbarandroid/index.html +++ b/docs/0.62/toolbarandroid/index.html @@ -16,7 +16,7 @@ ToolbarAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/touchablehighlight/index.html index d6e32a3e218..185bbc28000 100644 --- a/docs/0.62/touchablehighlight/index.html +++ b/docs/0.62/touchablehighlight/index.html @@ -16,7 +16,7 @@ TouchableHighlight · React Native - + @@ -31,7 +31,7 @@
Version: 0.62

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.

function MyComponent(props) {
return (
<View {...props} style={{ flex: 1, backgroundColor: '#fff' }}>
<Text>My Component</Text>
</View>
);
}
<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/index.html b/docs/0.62/touchablenativefeedback/index.html index 268b6619241..0bcc6bdee4d 100644 --- a/docs/0.62/touchablenativefeedback/index.html +++ b/docs/0.62/touchablenativefeedback/index.html @@ -16,7 +16,7 @@ TouchableNativeFeedback · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/touchableopacity/index.html index 66bdae8bed3..d44f499fff8 100644 --- a/docs/0.62/touchableopacity/index.html +++ b/docs/0.62/touchableopacity/index.html @@ -16,7 +16,7 @@ TouchableOpacity · React Native - + @@ -30,7 +30,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

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.62/touchablewithoutfeedback/index.html b/docs/0.62/touchablewithoutfeedback/index.html index bf702bc39d9..15e0674c2cf 100644 --- a/docs/0.62/touchablewithoutfeedback/index.html +++ b/docs/0.62/touchablewithoutfeedback/index.html @@ -16,7 +16,7 @@ TouchableWithoutFeedback · React Native - + @@ -31,7 +31,7 @@
Version: 0.62

TouchableWithoutFeedback

Do not use unless you have a very good reason. All elements that respond to press should have a visual feedback when touched.

TouchableWithoutFeedback supports only one child. If you wish to have several child components, wrap them in a View. Importantly, TouchableWithoutFeedback works by cloning its child and applying responder props to it. It is therefore required that any intermediary components pass through those props to the underlying React Native component.

Usage Pattern

function MyComponent(props) {
return (
<View {...props} style={{ flex: 1, backgroundColor: '#fff' }}>
<Text>My Component</Text>
</View>
);
}
<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:

  • '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

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/index.html b/docs/0.62/transforms/index.html index 6c2547e180b..bf821911ffb 100644 --- a/docs/0.62/transforms/index.html +++ b/docs/0.62/transforms/index.html @@ -16,7 +16,7 @@ Transforms · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/troubleshooting/index.html index c664b15b326..efd4c28b08c 100644 --- a/docs/0.62/troubleshooting/index.html +++ b/docs/0.62/troubleshooting/index.html @@ -16,7 +16,7 @@ Troubleshooting · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/tutorial/index.html index 1dbcf6e0ab4..5abba4eecb5 100644 --- a/docs/0.62/tutorial/index.html +++ b/docs/0.62/tutorial/index.html @@ -16,7 +16,7 @@ Learn the Basics · React Native - + @@ -30,7 +30,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.

There are 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/index.html b/docs/0.62/typescript/index.html index 50a339d49d6..510f7c7702e 100644 --- a/docs/0.62/typescript/index.html +++ b/docs/0.62/typescript/index.html @@ -16,7 +16,7 @@ Using TypeScript with React Native · React Native - + @@ -38,7 +38,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'
}
});
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/index.html b/docs/0.62/upgrading/index.html index c9b6eb39bd2..2fdb3323e18 100644 --- a/docs/0.62/upgrading/index.html +++ b/docs/0.62/upgrading/index.html @@ -16,7 +16,7 @@ Upgrading to new React Native versions · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/usecolorscheme/index.html index 4b9b841c6e3..a46ca834b62 100644 --- a/docs/0.62/usecolorscheme/index.html +++ b/docs/0.62/usecolorscheme/index.html @@ -16,7 +16,7 @@ useColorScheme · React Native - + @@ -31,7 +31,7 @@
Version: 0.62

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.
import { Text, useColorScheme } from 'react-native';
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/index.html b/docs/0.62/usewindowdimensions/index.html index 03aae638286..2d3403332be 100644 --- a/docs/0.62/usewindowdimensions/index.html +++ b/docs/0.62/usewindowdimensions/index.html @@ -16,7 +16,7 @@ useWindowDimensions · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/using-a-listview/index.html index 776bc9056d3..2607710a07b 100644 --- a/docs/0.62/using-a-listview/index.html +++ b/docs/0.62/using-a-listview/index.html @@ -16,7 +16,7 @@ Using List Views · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/using-a-scrollview/index.html index 59c1a508963..ab9d7ea0d67 100644 --- a/docs/0.62/using-a-scrollview/index.html +++ b/docs/0.62/using-a-scrollview/index.html @@ -16,7 +16,7 @@ Using a ScrollView · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/vibration/index.html index 788bd5f8d29..07ffad3f88c 100644 --- a/docs/0.62/vibration/index.html +++ b/docs/0.62/vibration/index.html @@ -16,7 +16,7 @@ Vibration · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/vibrationios/index.html index c8a9203878a..cbd9d3cb61e 100644 --- a/docs/0.62/vibrationios/index.html +++ b/docs/0.62/vibrationios/index.html @@ -16,7 +16,7 @@ VibrationIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/view-style-props/index.html index 785b535a571..afe215d0f87 100644 --- a/docs/0.62/view-style-props/index.html +++ b/docs/0.62/view-style-props/index.html @@ -16,7 +16,7 @@ View Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/view/index.html index 3026ef1d39d..30e6744c57d 100644 --- a/docs/0.62/view/index.html +++ b/docs/0.62/view/index.html @@ -16,7 +16,7 @@ View · React Native - + @@ -30,7 +30,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/index.html b/docs/0.62/viewpagerandroid/index.html index 4590badae9e..1fef48115e6 100644 --- a/docs/0.62/viewpagerandroid/index.html +++ b/docs/0.62/viewpagerandroid/index.html @@ -16,7 +16,7 @@ 🚧 ViewPagerAndroid · React Native - + @@ -32,7 +32,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.

  • '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

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:

  • position - index of first page from the left that is currently visible
  • offset - value from range [0, 1] describing stage between page transitions. Value x means that (1 - x) fraction of the page at "position" index is visible, and x fraction of the next page is visible.
TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

  • idle, meaning there is no interaction with the page scroller happening at the time
  • dragging, meaning there is currently an interaction with the page scroller
  • settling, meaning that there was an interaction with the page scroller, and the page scroller is now finishing its closing or opening animation
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:

  • position - index of page that has been selected
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.

  • position - index of page that will be selected
TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

  • position - index of page that will be selected
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/index.html b/docs/0.62/virtualizedlist/index.html index b1f080434fe..00bb3655c88 100644 --- a/docs/0.62/virtualizedlist/index.html +++ b/docs/0.62/virtualizedlist/index.html @@ -16,7 +16,7 @@ VirtualizedList · React Native - + @@ -33,7 +33,7 @@
- 'animated' (boolean). Optional default is true.

scrollToIndex()

scrollToIndex((params: object));

Valid params consist of:

  • 'animated' (boolean). Optional.
  • 'index' (number). Required.
  • 'viewOffset' (number). Optional.
  • 'viewPosition' (number). Optional.

scrollToItem()

scrollToItem((params: object));

Valid params consist of:

  • 'animated' (boolean). Optional.
  • 'item' (Item). Required.
  • 'viewPosition' (number). Optional.

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:

  • 'virtualizedList' (Object). This object consist of the following
    • getScrollMetrics' (Function). Returns an object with following properties: { contentLength: number, dOffset: number, dt: number, offset: number, timestamp: number, velocity: number, visibleLength: number }.
    • 'horizontal' (boolean) - Optional.
    • 'getOutermostParentListRef' (Function).
    • 'getNestedChildState' (Function) - Returns ChildListState .
    • 'registerAsNestedChild' (Function). This accept an object with following properties { cellKey: string, key: string, ref: VirtualizedList, parentDebugInfo: ListDebugInfo }. It returns a ChildListState
    • 'unregisterAsNestedChild' (Function). This takes an object with following properties, { key: string, state: ChildListState }
    • 'debugInfo' (ListDebugInfo).

hasMore()

hasMore () => boolean;
Edit this page
Last updated on
- + diff --git a/docs/0.62/webview/index.html b/docs/0.62/webview/index.html index b46eec4ee9a..3ef5ec88e60 100644 --- a/docs/0.62/webview/index.html +++ b/docs/0.62/webview/index.html @@ -16,7 +16,7 @@ 🚧 WebView · React Native - + @@ -32,7 +32,7 @@
class MyWeb extends Component {
render() {
return (
<WebView
source={{
uri: 'https://github.com/facebook/react-native'
}}
style={{ marginTop: 20 }}
/>
);
}
}

Minimal example with inline HTML:

import React, { Component } from 'react';
import { WebView } from 'react-native';
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

  • uri (string) - The URI to load in the WebView. Can be a local or remote file.
  • method (string) - The HTTP Method to use. Defaults to GET if not specified. On Android, the only supported methods are GET and POST.
  • headers (object) - Additional HTTP headers to send with the request. On Android, this can only be used with GET requests.
  • body (string) - The 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. On Android, this can only be used with POST requests.

Static HTML

  • html (string) - A static HTML page to display in the WebView.
  • baseUrl (string) - The base URL to be used for any relative links in the 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:

  • component (any)
  • props (object)
  • viewManager (object)
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:

  • normal: 0.998
  • fast: 0.99 (the default for iOS web view)
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:

  • never (default) - WebView will not allow a secure origin to load content from an insecure origin.
  • always - WebView will allow a secure origin to load content from any other origin, even if that origin is insecure.
  • compatibility - WebView will attempt to be compatible with the approach of a modern web browser with regard to mixed content.
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:

  • phoneNumber
  • link
  • address
  • calendarEvent
  • none
  • all

With the new WebKit implementation, we have three new values:

  • trackingNumber
  • flightNumber
  • lookupSuggestion
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/index.html b/docs/_getting-started-linux-android/index.html index 46442a4a3b5..344ac199c57 100644 --- a/docs/_getting-started-linux-android/index.html +++ b/docs/_getting-started-linux-android/index.html @@ -16,7 +16,7 @@ _getting-started-linux-android · React Native - + @@ -31,7 +31,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 intallation 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/index.html b/docs/_getting-started-macos-android/index.html index 3b03a810279..6666bbbc0b5 100644 --- a/docs/_getting-started-macos-android/index.html +++ b/docs/_getting-started-macos-android/index.html @@ -16,7 +16,7 @@ _getting-started-macos-android · React Native - + @@ -31,7 +31,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 cask install 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 intallation 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/index.html b/docs/_getting-started-macos-ios/index.html index 8cfe6941e91..4dc8b759f12 100644 --- a/docs/_getting-started-macos-ios/index.html +++ b/docs/_getting-started-macos-ios/index.html @@ -16,7 +16,7 @@ _getting-started-macos-ios · React Native - + @@ -31,7 +31,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/index.html b/docs/_getting-started-windows-android/index.html index 5e3001db832..00d33941384 100644 --- a/docs/_getting-started-windows-android/index.html +++ b/docs/_getting-started-windows-android/index.html @@ -16,7 +16,7 @@ _getting-started-windows-android · React Native - + @@ -31,7 +31,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.

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 intallation 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/index.html b/docs/_integration-with-exisiting-apps-java/index.html index 4d48b17bc01..11df533055c 100644 --- a/docs/_integration-with-exisiting-apps-java/index.html +++ b/docs/_integration-with-exisiting-apps-java/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-java · React Native - + @@ -45,7 +45,7 @@
@Override
protected void onDestroy() {
super.onDestroy();
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/index.html b/docs/_integration-with-exisiting-apps-objc/index.html index 8176e568801..00a257c11b2 100644 --- a/docs/_integration-with-exisiting-apps-objc/index.html +++ b/docs/_integration-with-exisiting-apps-objc/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-objc · React Native - + @@ -39,7 +39,7 @@
// Module name
AppRegistry.registerComponent('RNHighScores', () => RNHighScores);

RNHighScores is the name of your module that will be used when you add a view to React Native from within your iOS application.

The Magic: RCTRootView

Now that your React Native component is created via index.js, you need to add that component to a new or existing ViewController. The easiest path to take is to optionally create an event path to your component and then add that component to an existing ViewController.

We will tie our React Native component with a new native view in the ViewController that will actually contain it called RCTRootView .

1. Create an Event Path

You can add a new link on the main game menu to go to the "High Score" React Native page.

Event Path

2. Event Handler

We will now add an event handler from the menu link. A method will be added to the main ViewController of your application. This is where RCTRootView comes into play.

When you build a React Native application, you use the Metro bundler to create an index.bundle that will be served by the React Native server. Inside index.bundle will be our RNHighScore module. So, we need to point our RCTRootView to the location of the index.bundle resource (via NSURL) and tie it to the module.

We will, for debugging purposes, log that the event handler was invoked. Then, we will create a string with the location of our React Native code that exists inside the index.bundle. Finally, we will create the main RCTRootView. Notice how we provide RNHighScores as the moduleName that we created above when writing the code for our React Native component.

First import the RCTRootView header.

#import <React/RCTRootView.h>

The initialProperties are here for illustration purposes so we have some data for our high score screen. In our React Native component, we will use this.props to get access to that data.

- (IBAction)highScoreButtonPressed:(id)sender {
NSLog(@"High Score Button Pressed");
NSURL *jsCodeLocation = [NSURL URLWithString:@"http://localhost:8081/index.bundle?platform=ios"];
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/index.html b/docs/_integration-with-exisiting-apps-swift/index.html index d5f13c885f5..9e24f773458 100644 --- a/docs/_integration-with-exisiting-apps-swift/index.html +++ b/docs/_integration-with-exisiting-apps-swift/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-swift · React Native - + @@ -39,7 +39,7 @@
// Module name
AppRegistry.registerComponent('RNHighScores', () => RNHighScores);

RNHighScores is the name of your module that will be used when you add a view to React Native from within your iOS application.

The Magic: RCTRootView

Now that your React Native component is created via index.js, you need to add that component to a new or existing ViewController. The easiest path to take is to optionally create an event path to your component and then add that component to an existing ViewController.

We will tie our React Native component with a new native view in the ViewController that will actually contain it called RCTRootView .

1. Create an Event Path

You can add a new link on the main game menu to go to the "High Score" React Native page.

Event Path

2. Event Handler

We will now add an event handler from the menu link. A method will be added to the main ViewController of your application. This is where RCTRootView comes into play.

When you build a React Native application, you use the Metro bundler to create an index.bundle that will be served by the React Native server. Inside index.bundle will be our RNHighScore module. So, we need to point our RCTRootView to the location of the index.bundle resource (via NSURL) and tie it to the module.

We will, for debugging purposes, log that the event handler was invoked. Then, we will create a string with the location of our React Native code that exists inside the index.bundle. Finally, we will create the main RCTRootView. Notice how we provide RNHighScores as the moduleName that we created above when writing the code for our React Native component.

First import the React library.

import React

The initialProperties are here for illustration purposes so we have some data for our high score screen. In our React Native component, we will use this.props to get access to that data.

@IBAction func highScoreButtonTapped(sender : UIButton) {
NSLog("Hello")
let jsCodeLocation = URL(string: "http://localhost:8081/index.bundle?platform=ios")
let mockData:NSDictionary = ["scores":
[
["name":"Alex", "value":"42"],
["name":"Joel", "value":"10"]
]
]
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/index.html b/docs/accessibility/index.html index 9a695df3e2a..4a7008fff17 100644 --- a/docs/accessibility/index.html +++ b/docs/accessibility/index.html @@ -16,7 +16,7 @@ Accessibility · React Native - + @@ -32,7 +32,7 @@
if (Platform.OS === 'android') {
UIManager.sendAccessibilityEvent(
findNodeHandle(this),
UIManager.AccessibilityEventTypes.typeViewFocused
);
}

Testing TalkBack Support
Android

To enable TalkBack, go to the Settings app on your Android device or emulator. Tap Accessibility, then TalkBack. Toggle the "Use service" switch to enable or disable it.

P.S. Android emulator doesn’t have TalkBack by default. To install it:

  1. Download TalkBack file here: https://google-talkback.en.uptodown.com/android
  2. Drag the downloaded .apk file into the emulator

You can use the volume key shortcut to toggle TalkBack. To turn on the volume key shortcut, go to the Settings app, then Accessibility. At the top, turn on Volume key shortcut.

To use the volume key shortcut, press both volume keys for 3 seconds to start an accessibility tool.

Additionally, if you prefer, you can toggle TalkBack via command line with:

# disable
adb shell settings put secure enabled_accessibility_services com.android.talkback/com.google.android.marvin.talkback.TalkBackService
# 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/index.html b/docs/accessibilityinfo/index.html index cfe8dab76da..9a8575f1eef 100644 --- a/docs/accessibilityinfo/index.html +++ b/docs/accessibilityinfo/index.html @@ -16,7 +16,7 @@ AccessibilityInfo · React Native - + @@ -30,7 +30,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/index.html b/docs/actionsheetios/index.html index f1459f4590c..c107af427c3 100644 --- a/docs/actionsheetios/index.html +++ b/docs/actionsheetios/index.html @@ -16,7 +16,7 @@ ActionSheetIOS · React Native - + @@ -30,7 +30,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

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/index.html b/docs/activityindicator/index.html index 1a45043b6d3..afe430a6f9e 100644 --- a/docs/activityindicator/index.html +++ b/docs/activityindicator/index.html @@ -16,7 +16,7 @@ ActivityIndicator · React Native - + @@ -30,7 +30,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/index.html b/docs/alert/index.html index 85435b94502..6addf8ba1d7 100644 --- a/docs/alert/index.html +++ b/docs/alert/index.html @@ -16,7 +16,7 @@ Alert · React Native - + @@ -30,7 +30,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/index.html b/docs/alertios/index.html index 8b16b752541..1ce0c1e47fb 100644 --- a/docs/alertios/index.html +++ b/docs/alertios/index.html @@ -16,7 +16,7 @@ 🚧 AlertIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/animated/index.html index 097d265826e..6ad322da424 100644 --- a/docs/animated/index.html +++ b/docs/animated/index.html @@ -16,7 +16,7 @@ Animated · React Native - + @@ -30,7 +30,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/index.html b/docs/animatedvalue/index.html index fab5010dd67..899637b7db2 100644 --- a/docs/animatedvalue/index.html +++ b/docs/animatedvalue/index.html @@ -16,7 +16,7 @@ Animated.Value · React Native - + @@ -30,7 +30,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/index.html b/docs/animatedvaluexy/index.html index c4f867cac08..44d6e632db9 100644 --- a/docs/animatedvaluexy/index.html +++ b/docs/animatedvaluexy/index.html @@ -16,7 +16,7 @@ Animated.ValueXY · React Native - + @@ -30,7 +30,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/index.html b/docs/animations/index.html index 95c45e2aa59..58f7b9c1abc 100644 --- a/docs/animations/index.html +++ b/docs/animations/index.html @@ -16,7 +16,7 @@ Animations · React Native - + @@ -31,7 +31,7 @@

Animations

Animations are very important to create a great user experience. Stationary objects must overcome inertia as they start moving. Objects in motion have momentum and rarely come to a stop immediately. Animations allow you to convey physically believable motion in your interface.

React Native provides two complementary animation systems: Animated for granular and interactive control of specific values, and LayoutAnimation for animated global layout transactions.

Animated API

The Animated API is designed to concisely express a wide variety of interesting animation and interaction patterns in a very performant way. Animated focuses on declarative relationships between inputs and outputs, with configurable transforms in between, and start/stop methods to control time-based animation execution.

Animated exports six animatable component types: View, Text, Image, ScrollView, FlatList and SectionList, but you can also create your own using Animated.createAnimatedComponent().

For example, a container view that fades in when it is mounted may look like this:

Let's break down what's happening here. In the FadeInView constructor, a new Animated.Value called fadeAnim is initialized as part of state. The opacity property on the View is mapped to this animated value. Behind the scenes, the numeric value is extracted and used to set opacity.

When the component mounts, the opacity is set to 0. Then, an easing animation is started on the fadeAnim animated value, which will update all of its dependent mappings (in this case, only the opacity) on each frame as the value animates to the final value of 1.

This is done in an optimized way that is faster than calling setState and re-rendering. Because the entire configuration is declarative, we will be able to implement further optimizations that serialize the configuration and runs the animation on a high-priority thread.

Configuring animations

Animations are heavily configurable. Custom and predefined easing functions, delays, durations, decay factors, spring constants, and more can all be tweaked depending on the type of animation.

Animated provides several animation types, the most commonly used one being Animated.timing(). It supports animating a value over time using one of various predefined easing functions, or you can use your own. Easing functions are typically used in animation to convey gradual acceleration and deceleration of objects.

By default, timing will use an easeInOut curve that conveys gradual acceleration to full speed and concludes by gradually decelerating to a stop. You can specify a different easing function by passing an easing parameter. Custom duration or even a delay before the animation starts is also supported.

For example, if we want to create a 2-second long animation of an object that slightly backs up before moving to its final position:

Animated.timing(this.state.xPosition, {
toValue: 100,
easing: Easing.back(),
duration: 2000
}).start();

Take a look at the Configuring animations section of the Animated API reference to learn more about all the config parameters supported by the built-in animations.

Composing animations

Animations can be combined and played in sequence or in parallel. Sequential animations can play immediately after the previous animation has finished, or they can start after a specified delay. The Animated API provides several methods, such as sequence() and delay(), each of which take an array of animations to execute and automatically calls start()/stop() as needed.

For example, the following animation coasts to a stop, then it springs back while twirling in parallel:

Animated.sequence([
// decay, then spring to start and twirl
Animated.decay(position, {
// coast to a stop
velocity: { x: gestureState.vx, y: gestureState.vy }, // velocity from gesture release
deceleration: 0.997
}),
Animated.parallel([
// after decay, in parallel:
Animated.spring(position, {
toValue: { x: 0, y: 0 } // return to start
}),
Animated.timing(twirl, {
// and twirl
toValue: 360
})
])
]).start(); // start the sequence group

If one animation is stopped or interrupted, then all other animations in the group are also stopped. Animated.parallel has a stopTogether option that can be set to false to disable this.

You can find a full list of composition methods in the Composing animations section of the Animated API reference.

Combining animated values

You can combine two animated values via addition, multiplication, division, or modulo to make a new animated value.

There are some cases where an animated value needs to invert another animated value for calculation. An example is inverting a scale (2x --> 0.5x):

const a = new Animated.Value(1);
const b = Animated.divide(1, a);
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:

  • spring.stopAnimation(callback) will stop the animation and invoke callback with the final value. This is useful when making gesture transitions.
  • spring.addListener(callback) will invoke callback asynchronously while the animation is running, providing a recent value. This is useful for triggering state changes, for example snapping a bobble to a new option as the user drags it closer, because these larger state changes are less sensitive to a few frames of lag compared to continuous gestures like panning which need to run at 60 fps.

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/index.html b/docs/app-extensions/index.html index 2e9a3c5e340..d67896376f0 100644 --- a/docs/app-extensions/index.html +++ b/docs/app-extensions/index.html @@ -16,7 +16,7 @@ App Extensions · React Native - + @@ -30,7 +30,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/index.html b/docs/appearance/index.html index fb028c32524..ab60675556a 100644 --- a/docs/appearance/index.html +++ b/docs/appearance/index.html @@ -16,7 +16,7 @@ Appearance · React Native - + @@ -30,7 +30,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/index.html b/docs/appregistry/index.html index 6a52d26688c..7b19e3e27a7 100644 --- a/docs/appregistry/index.html +++ b/docs/appregistry/index.html @@ -16,7 +16,7 @@ AppRegistry · React Native - + @@ -32,7 +32,7 @@
const App = (props) => (
<View>
<Text>App1</Text>
</View>
);
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:

  • 'appKey' (string)- Required.
  • 'component' (ComponentProvider) - Optional.
  • 'run' (Function) - Optional.
  • 'section' (boolean) - Optional.

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:

  • 'component' (ComponentProvider).
  • 'run' (Function).

getRunnable()

static getRunnable(appKey)

Returns a Runnable object which consist of:

  • 'component' (ComponentProvider).
  • 'run' (Function).

getRegistry()

static getRegistry()

Returns a type Registry which consist of:

  • 'sections' (Array of strings).
  • 'runnables' (Runnables).

setComponentProviderInstrumentationHook()

static setComponentProviderInstrumentationHook(hook)

Parameters:

NameTypeRequiredDescription
hookFunctionyesSee below.

A valid hook accepts the following as arguments:

  • 'component' (ComponentProvider)- Required.
  • 'scopedPerformanceLogger' (IPerformanceLogger)- Required.

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.
  • A valid TaskProvider is a function that returns a Task.
  • A Task is a function that accepts any data as argument and returns a Promise that resolves to undefined.

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.
  • A valid TaskProvider is a function that returns a Task.
  • A Task is a function that accepts any data as argument and returns a Promise that resolves to undefined.
  • A valid TaskCancelProvider is a function that returns a TaskCanceller.
  • A TaskCanceller is a function that accepts no argument and returns void.

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/index.html b/docs/appstate/index.html index 4316b6553fd..1fe6967d1ad 100644 --- a/docs/appstate/index.html +++ b/docs/appstate/index.html @@ -16,7 +16,7 @@ AppState · React Native - + @@ -30,7 +30,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/index.html b/docs/asyncstorage/index.html index b7b21878fb3..17c9f5efe49 100644 --- a/docs/asyncstorage/index.html +++ b/docs/asyncstorage/index.html @@ -16,7 +16,7 @@ 🚧 AsyncStorage · React Native - + @@ -38,7 +38,7 @@
AsyncStorage.multiSet(multi_set_pairs, (err) => {
AsyncStorage.multiMerge(multi_merge_pairs, (err) => {
AsyncStorage.multiGet(['UID234', 'UID345'], (err, stores) => {
stores.map((result, i, store) => {
let key = store[i][0];
let val = store[i][1];
console.log(key, val);
});
});
});
});
// 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/index.html b/docs/backandroid/index.html index 7d939221066..91d98858c62 100644 --- a/docs/backandroid/index.html +++ b/docs/backandroid/index.html @@ -16,7 +16,7 @@ BackAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/backhandler/index.html index 94d088b405e..dc3311fc9fe 100644 --- a/docs/backhandler/index.html +++ b/docs/backhandler/index.html @@ -16,7 +16,7 @@ BackHandler · React Native - + @@ -31,7 +31,7 @@

BackHandler

The Backhandler API detects hardware button presses for back navigation, lets you register event listeners for the system's back action, and lets you control how your application responds. It is Android-only.

The event subscriptions are called in reverse order (i.e. the last registered subscription is called first).

  • If one subscription returns true, then subscriptions registered earlier will not be called.
  • If no subscription returns true or none are registered, it programmatically invokes the default back button functionality to exit the app.

Warning for modal users: If your app shows an opened Modal, BackHandler will not publish any events (see Modal docs).

Pattern

BackHandler.addEventListener('hardwareBackPress', function() {
/**
* this.onMainScreen and this.goBack are just examples,
* you need to use your own implementation here.
*
* Typically you would use the navigator here to go to the last state.
*/
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/index.html b/docs/building-for-tv/index.html index 086f5bb4ede..4d66ab183e1 100644 --- a/docs/building-for-tv/index.html +++ b/docs/building-for-tv/index.html @@ -16,7 +16,7 @@ Building For TV Devices · React Native - + @@ -35,7 +35,7 @@
componentDidMount() {
this._enableTVEventHandler();
}
componentWillUnmount() {
this._disableTVEventHandler();
}
}

  • Dev Menu support: On the simulator, cmd-M will bring up the developer menu, similar to Android. To bring it up on a real Android TV device, press the menu button or long press the fast-forward button on the remote. (Please do not shake the Android TV device, that will not work :) )

  • Known issues:

    • InputText components do not work for now (i.e. they cannot receive focus).
Edit this page
Last updated on
- + diff --git a/docs/button/index.html b/docs/button/index.html index 3c4b6189124..e82cb5f3c35 100644 --- a/docs/button/index.html +++ b/docs/button/index.html @@ -16,7 +16,7 @@ Button · React Native - + @@ -30,7 +30,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/index.html b/docs/cameraroll/index.html index 764e429d302..16579765a6d 100644 --- a/docs/cameraroll/index.html +++ b/docs/cameraroll/index.html @@ -16,7 +16,7 @@ 🚧 CameraRoll · React Native - + @@ -30,7 +30,7 @@

🚧 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/checkbox/index.html b/docs/checkbox/index.html index 5d3aeb14b95..1d998a5ec90 100644 --- a/docs/checkbox/index.html +++ b/docs/checkbox/index.html @@ -16,7 +16,7 @@ 🚧 CheckBox · React Native - + @@ -30,7 +30,7 @@

🚧 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/clipboard/index.html b/docs/clipboard/index.html index 944899c73d5..3d3c2430386 100644 --- a/docs/clipboard/index.html +++ b/docs/clipboard/index.html @@ -16,7 +16,7 @@ 🚧 Clipboard · React Native - + @@ -30,7 +30,7 @@

🚧 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/colors/index.html b/docs/colors/index.html index 0931fca2c0a..3ec7f55c309 100644 --- a/docs/colors/index.html +++ b/docs/colors/index.html @@ -16,7 +16,7 @@ Color Reference · React Native - + @@ -30,7 +30,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/index.html b/docs/communication-android/index.html index bf14df50b32..f1011407f48 100644 --- a/docs/communication-android/index.html +++ b/docs/communication-android/index.html @@ -16,7 +16,7 @@ Communication between native and React Native · React Native - + @@ -32,7 +32,7 @@
export default class ImageBrowserApp extends React.Component {
renderImage(imgURI) {
return <Image source={{ uri: imgURI }} />;
}
render() {
return <View>{this.props.images.map(this.renderImage)}</View>;
}
}

ReactRootView provides a read-write property appProperties. After appProperties is set, the React Native app is re-rendered with new properties. The update is only performed when the new updated properties differ from the previous ones.

Bundle updatedProps = mReactRootView.getAppProperties();
ArrayList<String> imageList = new ArrayList<String>(Arrays.asList(
"http://foo.com/bar3.png",
"http://foo.com/bar4.png"
));
updatedProps.putStringArrayList("images", imageList);
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:

  • As events can be sent from anywhere, they can introduce spaghetti-style dependencies into your project.
  • Events share namespace, which means that you may encounter some name collisions. Collisions will not be detected statically, which makes them hard to debug.
  • If you use several instances of the same React Native component and you want to distinguish them from the perspective of your event, you'll likely need to introduce identifiers and pass them along with events (you can use the native view's reactTag as an identifier).

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/index.html b/docs/communication-ios/index.html index e92319f53fd..657101d7ef7 100644 --- a/docs/communication-ios/index.html +++ b/docs/communication-ios/index.html @@ -16,7 +16,7 @@ Communication between native and React Native · React Native - + @@ -41,7 +41,7 @@
#pragma mark - RCTRootViewDelegate
- (void)rootViewDidChangeIntrinsicSize:(RCTRootView *)rootView
{
CGRect newFrame = rootView.frame;
newFrame.size = rootView.intrinsicContentSize;
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/index.html b/docs/components-and-apis/index.html index 97f8a4e5c1e..57f3848ff52 100644 --- a/docs/components-and-apis/index.html +++ b/docs/components-and-apis/index.html @@ -16,7 +16,7 @@ Core Components and APIs · React Native - + @@ -30,7 +30,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.

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/custom-webview-android/index.html b/docs/custom-webview-android/index.html index 6ab461551a0..95f60eaef7b 100644 --- a/docs/custom-webview-android/index.html +++ b/docs/custom-webview-android/index.html @@ -16,7 +16,7 @@ Custom WebView · React Native - + @@ -57,7 +57,7 @@
_onNavigationCompleted = (event) => {
const { onNavigationCompleted } = this.props;
onNavigationCompleted && onNavigationCompleted(event);
};
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/index.html b/docs/custom-webview-ios/index.html index 6d5cea4a14b..c7b55769e3d 100644 --- a/docs/custom-webview-ios/index.html +++ b/docs/custom-webview-ios/index.html @@ -16,7 +16,7 @@ Custom WebView · React Native - + @@ -60,7 +60,7 @@
_onNavigationCompleted = (event) => {
const { onNavigationCompleted } = this.props;
onNavigationCompleted && onNavigationCompleted(event);
};
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/index.html b/docs/datepickerandroid/index.html index bff401eb7ec..528ca8ccf3d 100644 --- a/docs/datepickerandroid/index.html +++ b/docs/datepickerandroid/index.html @@ -16,7 +16,7 @@ 🚧 DatePickerAndroid · React Native - + @@ -30,7 +30,7 @@

🚧 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/datepickerios/index.html b/docs/datepickerios/index.html index cda0dc942c4..249e8e51da3 100644 --- a/docs/datepickerios/index.html +++ b/docs/datepickerios/index.html @@ -16,7 +16,7 @@ 🚧 DatePickerIOS · React Native - + @@ -30,7 +30,7 @@

🚧 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/debugging/index.html b/docs/debugging/index.html index 6269fe2d972..94d8d042d8f 100644 --- a/docs/debugging/index.html +++ b/docs/debugging/index.html @@ -16,7 +16,7 @@ Debugging · React Native - + @@ -32,7 +32,7 @@
// Ignore log notification by message:
LogBox.ignoreLogs(['Warning: ...']);
// 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".

  • 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/devsettings/index.html b/docs/devsettings/index.html index ee9980bdc86..5135d789091 100644 --- a/docs/devsettings/index.html +++ b/docs/devsettings/index.html @@ -16,7 +16,7 @@ DevSettings · React Native - + @@ -30,7 +30,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/index.html b/docs/dimensions/index.html index d4d18b5b08a..7ff50316f7e 100644 --- a/docs/dimensions/index.html +++ b/docs/dimensions/index.html @@ -16,7 +16,7 @@ Dimensions · React Native - + @@ -30,7 +30,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/index.html b/docs/direct-manipulation/index.html index f88ab726b91..7c537f67556 100644 --- a/docs/direct-manipulation/index.html +++ b/docs/direct-manipulation/index.html @@ -16,7 +16,7 @@ Direct Manipulation · React Native - + @@ -31,7 +31,7 @@

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:

setOpacityTo(value) {
// Redacted: animation related code
this.refs[CHILD_REF].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={this._handlePress}>
<View style={styles.button}>
<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:

constructor(props) {
super(props);
this.state = { myButtonOpacity: 1, };
}
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:

  • 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 prop instead.

measureInWindow(callback)

Determines the location of the given view in the window and returns the values via an async callback. If the React root view is embedded in another native view, this will give you the absolute coordinates. If successful, the callback will be called with the following arguments:

  • x
  • y
  • width
  • height

measureLayout(relativeToNativeNode, onSuccess, onFail)

Like measure(), but measures the view relative 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/index.html b/docs/drawerlayoutandroid/index.html index 0991a8402bc..23d8d0b4f4c 100644 --- a/docs/drawerlayoutandroid/index.html +++ b/docs/drawerlayoutandroid/index.html @@ -16,7 +16,7 @@ DrawerLayoutAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/dynamiccolorios/index.html index 721fe4f56d6..4249f66fcf5 100644 --- a/docs/dynamiccolorios/index.html +++ b/docs/dynamiccolorios/index.html @@ -16,7 +16,7 @@ DynamicColorIOS · React Native - + @@ -31,7 +31,7 @@

DynamicColorIOS

The DynamicColorIOS function is a platform color type specific to iOS.

DynamicColorIOS({ light: color, dark: color });

DynamicColorIOS takes a single argument as an object with two keys: dark and light. These correspond to the colors you want to use for "light mode" and "dark mode" on iOS.

In the future, more keys might become available for different user preferences, like high contrast.

At runtime, the system will choose which of the two colors to display depending on the current system appearance settings. Dynamic colors are useful for branding colors or other app specific colors that still respond automatically to system setting changes.

Developer notes

If you’re familiar with @media (prefers-color-scheme: dark) in CSS, this is similar! Only instead of defining all the colors in a media query, you define which color to use under what circumstances right there where you're using it. Neat!

Example

import { DynamicColorIOS } from 'react-native';
const customDynamicTextColor = DynamicColorIOS({
dark: 'lightskyblue',
light: 'midnightblue'
});
Edit this page
Last updated on
- + diff --git a/docs/easing/index.html b/docs/easing/index.html index dacb6ef2072..8f67e197b66 100644 --- a/docs/easing/index.html +++ b/docs/easing/index.html @@ -16,7 +16,7 @@ Easing · React Native - + @@ -30,7 +30,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/index.html b/docs/environment-setup/index.html index fa3a21fc3e5..7cbeea3def0 100644 --- a/docs/environment-setup/index.html +++ b/docs/environment-setup/index.html @@ -16,7 +16,7 @@ Setting up the development environment · React Native - + @@ -32,7 +32,7 @@

Setting up the development environment

This page will help you install and build your first React Native app.

If you are new to mobile development, the easiest way to get started is with Expo CLI. Expo is a set of tools built around React Native and, while it has many features, the most relevant feature for us right now is that it can get you writing a React Native app within minutes. You will only need a recent version of Node.js and a phone or emulator. If you'd like to try out React Native directly in your web browser before installing any tools, you can try out Snack.

If you are already familiar with mobile development, you may want to use React Native CLI. It requires Xcode or Android Studio to get started. If you already have one of these tools installed, you should be able to get up and running within a few minutes. If they are not installed, you should expect to spend about an hour installing and configuring them.

Assuming that you have Node 12 LTS or greater installed, you can use npm to install the Expo CLI command line utility:

npm install -g expo-cli

Then run the following commands to create a new React Native project called "AwesomeProject":

expo init AwesomeProject
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/index.html b/docs/fast-refresh/index.html index 11eaf5aa05d..c7a0fda6a6a 100644 --- a/docs/fast-refresh/index.html +++ b/docs/fast-refresh/index.html @@ -16,7 +16,7 @@ Fast Refresh · React Native - + @@ -30,7 +30,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/index.html b/docs/flatlist/index.html index 0838412993e..987b194caee 100644 --- a/docs/flatlist/index.html +++ b/docs/flatlist/index.html @@ -16,7 +16,7 @@ FlatList · React Native - + @@ -31,7 +31,7 @@

FlatList

A performant interface for rendering basic, flat lists, supporting the most handy features:

  • Fully cross-platform.
  • Optional horizontal mode.
  • Configurable viewability callbacks.
  • Header support.
  • Footer support.
  • Separator support.
  • Pull to Refresh.
  • Scroll loading.
  • ScrollToIndex support.
  • Multiple column support.

If you need section support, use <SectionList>.

Example

To render multiple columns, use the numColumns prop. Using this approach instead of a flexWrap layout can prevent conflicts with the item height logic.

More complex, multi-select example demonstrating `` usage for perf optimization and avoiding bugs.

  • By passing extraData={selected} to FlatList we make sure FlatList itself will re-render when the state changes. Without setting this prop, FlatList would not know it needs to re-render any items because it is a PureComponent and the prop comparison will not show any changes.
  • keyExtractor tells the list to use the ids for the react keys instead of the default key property.

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, unless it is nested in another FlatList of same orientation.

renderItem

renderItem({ item, index, separators });

Takes an item from data and renders it into the list.

Provides additional metadata like index if you need it, as well as a more generic separators.updateProps function which let you set whatever props you want to change the rendering of either the leading separator or trailing separator in case the more common highlight and unhighlight (which set the highlighted: boolean prop) are insufficient for your use case.

TypeRequired
functionYes
  • item (Object): The item from data being rendered.
  • index (number): The index corresponding to this item in the data array.
  • separators (Object)
    • highlight (Function)
    • unhighlight (Function)
    • updateProps (Function)
      • select (enum('leading', 'trailing'))
      • newProps (Object)

Example usage:

<FlatList
ItemSeparatorComponent={
Platform.OS !== 'android' &&
(({ highlighted }) => (
<View
style={[
style.separator,
highlighted && { marginLeft: 0 }
]}
/>
))
}
data={[{ title: 'Title Text', key: 'item1' }]}
renderItem={({ item, index, separators }) => (
<TouchableHighlight
key={item.key}
onPress={() => this._onPress(item)}
onShowUnderlay={separators.highlight}
onHideUnderlay={separators.unhighlight}>
<View style={{ backgroundColor: 'white' }}>
<Text>{item.title}</Text>
</View>
</TouchableHighlight>
)}
/>

data

For simplicity, data is a plain array. If you want to use something else, like an immutable list, use the underlying VirtualizedList directly.

TypeRequired
arrayYes

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted and leadingItem 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
componentNo

ListEmptyComponent

Rendered when the list is empty. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListFooterComponent

Rendered at the bottom of all the items. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListFooterComponentStyle

Styling for internal View for ListFooterComponent

TypeRequired
style objectNo

ListHeaderComponent

Rendered at the top of all the items. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListHeaderComponentStyle

Styling for internal View for ListHeaderComponent

TypeRequired
style objectNo

columnWrapperStyle

Optional custom style for multi-item rows generated when numColumns > 1.

TypeRequired
style objectNo

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, index) => {length: number, offset: number, index: number}

getItemLayout is an optional optimization that allows skipping the measurement of dynamic content if you know the size (height or width) of items ahead of time. getItemLayout is efficient if you have fixed size items, for example:

getItemLayout={(data, index) => (
{length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index}
)}

Adding getItemLayout can be a great performance boost for lists of several hundred items. Remember to include separator length (height or width) in your offset calculation if you specify ItemSeparatorComponent.

TypeRequired
functionNo

horizontal

If true, renders items next to each other horizontally instead of stacked vertically.

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

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

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 falls back to using the index, like React does.

TypeRequired
functionNo

numColumns

Multiple columns can only be rendered with horizontal={false} and will zig-zag like a flexWrap layout. Items should all be the same height - masonry layouts are not supported.

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

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

onViewableItemsChanged

(info: {
viewableItems: array,
changed: array,
}) => void

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

progressViewOffset

Set this when offset is needed for the loading indicator to show correctly.

TypeRequiredPlatform
numberNoAndroid

legacyImplementation

May not have full feature parity and is meant for debugging and performance comparison.

TypeRequired
booleanNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
booleanNo

removeClippedSubviews

This may improve scroll performance for large lists. On Android the default value is true

Note: May have bugs (missing content) in some circumstances - use at your own risk.

TypeRequired
booleanNo

viewabilityConfig

See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
ViewabilityConfigNo

viewabilityConfig takes a type ViewabilityConfig an object with following properties

PropertyRequiredType
minimumViewTimeNonumber
viewAreaCoveragePercentThresholdNonumber
itemVisiblePercentThresholdNonumber
waitForInteractionNoboolean

At least one of the viewAreaCoveragePercentThreshold or itemVisiblePercentThreshold is required. This needs to be done in the constructor to avoid following error (ref):

Error: Changing viewabilityConfig on the fly is not supported`
constructor (props) {
super(props)
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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.

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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'index' (number) - The index to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position.
  • '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.

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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'item' (object) - The item to scroll to. Required.
  • 'viewPosition' (number)

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'offset' (number) - The offset to scroll to. In case of horizontal being true, the offset is the x-value, in any other case the offset is the y-value. Required.
  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.

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/index.html b/docs/flexbox/index.html index 9c5a88de44b..99c85e8d929 100644 --- a/docs/flexbox/index.html +++ b/docs/flexbox/index.html @@ -16,7 +16,7 @@ Layout with Flexbox · React Native - + @@ -30,7 +30,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, 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/geolocation/index.html b/docs/geolocation/index.html index 83dec87cd24..b2eb0acfde5 100644 --- a/docs/geolocation/index.html +++ b/docs/geolocation/index.html @@ -16,7 +16,7 @@ 🚧 Geolocation · React Native - + @@ -30,7 +30,7 @@

🚧 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/gesture-responder-system/index.html b/docs/gesture-responder-system/index.html index 566d21707f7..6f71867de6f 100644 --- a/docs/gesture-responder-system/index.html +++ b/docs/gesture-responder-system/index.html @@ -16,7 +16,7 @@ Gesture Responder System · React Native - + @@ -30,7 +30,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/index.html b/docs/getting-started/index.html index 6ae1fe3914e..1ce99977a64 100644 --- a/docs/getting-started/index.html +++ b/docs/getting-started/index.html @@ -16,7 +16,7 @@ Introduction · React Native - + @@ -30,7 +30,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.58., 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/index.html b/docs/handling-text-input/index.html index 6b4f017644e..f61f4da4162 100644 --- a/docs/handling-text-input/index.html +++ b/docs/handling-text-input/index.html @@ -16,7 +16,7 @@ Handling Text Input · React Native - + @@ -30,7 +30,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/index.html b/docs/handling-touches/index.html index 86f5db91bc0..84b35a9de37 100644 --- a/docs/handling-touches/index.html +++ b/docs/handling-touches/index.html @@ -16,7 +16,7 @@ Handling Touches · React Native - + @@ -30,7 +30,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, 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/headless-js-android/index.html b/docs/headless-js-android/index.html index bdfb34c0118..47942d8f1f8 100644 --- a/docs/headless-js-android/index.html +++ b/docs/headless-js-android/index.html @@ -16,7 +16,7 @@ Headless JS · React Native - + @@ -41,7 +41,7 @@
}
Edit this page
Last updated on
- + diff --git a/docs/height-and-width/index.html b/docs/height-and-width/index.html index b865a666b7a..61f5191ae93 100644 --- a/docs/height-and-width/index.html +++ b/docs/height-and-width/index.html @@ -16,7 +16,7 @@ Height and Width · React Native - + @@ -30,7 +30,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/index.html b/docs/hermes/index.html index 1ed059edc7d..1adf3eb633f 100644 --- a/docs/hermes/index.html +++ b/docs/hermes/index.html @@ -16,7 +16,7 @@ Using Hermes · React Native - + @@ -30,7 +30,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 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 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/image-style-props/index.html b/docs/image-style-props/index.html index dea82cefb12..785ae30b520 100644 --- a/docs/image-style-props/index.html +++ b/docs/image-style-props/index.html @@ -16,7 +16,7 @@ Image Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/image/index.html index 2793ede8679..28bbc946457 100644 --- a/docs/image/index.html +++ b/docs/image/index.html @@ -16,7 +16,7 @@ Image · React Native - + @@ -33,7 +33,7 @@
// For WebP support, including animated WebP
implementation 'com.facebook.fresco:animated-webp:2.1.0'
implementation 'com.facebook.fresco:webpsupport:2.0.0'
// 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}:

  • 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 (which should be wrapped in the require('./path/to/image.png') function).
  • width, height - can be specified if known at build time, in which case these will be used to set the default <Image/> component dimensions.
  • scale - used 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.

If passing a number:

  • number - Opaque type returned by something like require('./image.jpg').

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.

  • auto: Use heuristics to pick between resize and scale.

  • resize: A software operation which changes the encoded image in memory before it gets decoded. This should be used instead of scale when the image is much larger than the view.

  • scale: The image gets drawn downscaled or upscaled. Compared to resize, scale is faster (usually hardware accelerated) and produces higher quality images. This should be used if the image is smaller than the view. It should also be used if the image is slightly bigger than the view.

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.

  • cover: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or larger than the corresponding dimension of the view (minus padding).

  • contain: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or less than the corresponding dimension of the view (minus padding).

  • stretch: Scale width and height independently, This may change the aspect ratio of the src.

  • repeat: Repeat the image to cover the frame of the view. The image will keep its size and aspect ratio, unless it is larger than the view, in which case it will be scaled down uniformly so that it is contained in the view.

  • center: Center the image in the view along both dimensions. If the image is larger than the view, scale it down uniformly so that it is contained in the view.

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/imagebackground/index.html b/docs/imagebackground/index.html index d6007076540..85c3a8f6e86 100644 --- a/docs/imagebackground/index.html +++ b/docs/imagebackground/index.html @@ -16,7 +16,7 @@ ImageBackground · React Native - + @@ -30,7 +30,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/index.html b/docs/imageeditor/index.html index 4f25065caff..21f607c2e11 100644 --- a/docs/imageeditor/index.html +++ b/docs/imageeditor/index.html @@ -16,7 +16,7 @@ 🚧 ImageEditor · React Native - + @@ -30,7 +30,7 @@

🚧 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/imagepickerios/index.html b/docs/imagepickerios/index.html index b2f60f3c204..effcfcb6e7a 100644 --- a/docs/imagepickerios/index.html +++ b/docs/imagepickerios/index.html @@ -16,7 +16,7 @@ 🚧 ImagePickerIOS · React Native - + @@ -30,7 +30,7 @@

🚧 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/images/index.html b/docs/images/index.html index 724003da2c9..10994ea2c08 100644 --- a/docs/images/index.html +++ b/docs/images/index.html @@ -16,7 +16,7 @@ Images · React Native - + @@ -33,7 +33,7 @@
// GOOD
var icon = this.props.active
? require('./my-icon-active.png')
: require('./my-icon-inactive.png');
<Image source={icon} />;

Note that image sources required this way include size (width, height) info for the Image. If you need to scale the image dynamically (i.e. via flex), you may need to manually set { width: undefined, height: undefined } on the style attribute.

Static Non-Image Resources

The require syntax described above can be used to statically include audio, video or document files in your project as well. Most common file types are supported including .mp3, .wav, .mp4, .mov, .html and .pdf. See bundler defaults for the full list.

You can add support for other types by adding an assetExts resolver option in your Metro configuration.

A caveat is that videos must use absolute positioning instead of flexGrow, since size info is not currently passed for non-image assets. This limitation doesn't occur for videos that are linked directly into Xcode or the Assets folder for Android.

Images From Hybrid App's Resources

If you are building a hybrid app (some UIs in React Native, some UIs in platform code) you can still use images that are already bundled into the app.

For images included via Xcode asset catalogs or in the Android drawable folder, use the image name without the extension:

<Image
source={{ uri: 'app_icon' }}
style={{ width: 40, height: 40 }}
/>

For images in the Android assets folder, use the asset:/ scheme:

<Image
source={{ uri: 'asset:/app_icon.png' }}
style={{ width: 40, height: 40 }}
/>

These approaches provide no safety checks. It's up to you to guarantee that those images are available in the application. Also you have to specify image dimensions manually.

Network Images

Many of the images you will display in your app will not be available at compile time, or you will want to load some dynamically to keep the binary size down. Unlike with static resources, you will need to manually specify the dimensions of your image. It's highly recommended that you use https as well in order to satisfy App Transport Security requirements on iOS.

// GOOD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}}
style={{width: 400, height: 400}} />
// 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.

  • default: Use the native platforms default strategy.
  • reload: The data for the URL will be loaded from the originating source. No existing cache data should be used to satisfy a URL load request.
  • force-cache: The existing cached data will be used to satisfy the request, regardless of its age or expiration date. If there is no existing data in the cache corresponding the request, the data is loaded from the originating source.
  • only-if-cached: The existing cache data will be used to satisfy a request, regardless of its age or expiration date. If there is no existing data in the cache corresponding to a URL load request, no attempt is made to load the data from the originating source, and the load is considered to have failed.
<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:

  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomLeftRadius
  • borderBottomRightRadius

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/index.html b/docs/imagestore/index.html index a7fa84850d0..18392e559d2 100644 --- a/docs/imagestore/index.html +++ b/docs/imagestore/index.html @@ -16,7 +16,7 @@ ImageStore · React Native - + @@ -30,7 +30,7 @@

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/improvingux/index.html b/docs/improvingux/index.html index 8d2cdceba05..6a8f0d0e230 100644 --- a/docs/improvingux/index.html +++ b/docs/improvingux/index.html @@ -16,7 +16,7 @@ Improving User Experience · React Native - + @@ -30,7 +30,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/index.html b/docs/inputaccessoryview/index.html index a712322acc4..028e9d3e5ee 100644 --- a/docs/inputaccessoryview/index.html +++ b/docs/inputaccessoryview/index.html @@ -16,7 +16,7 @@ InputAccessoryView · React Native - + @@ -30,7 +30,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/index.html b/docs/integration-with-existing-apps/index.html index 7b90fa76af8..96b4dc0f17f 100644 --- a/docs/integration-with-existing-apps/index.html +++ b/docs/integration-with-existing-apps/index.html @@ -16,7 +16,7 @@ Integration with Existing Apps · React Native - + @@ -45,7 +45,7 @@
@Override
protected void onDestroy() {
super.onDestroy();
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/index.html b/docs/interactionmanager/index.html index 8f68363eb67..7e8affc58d8 100644 --- a/docs/interactionmanager/index.html +++ b/docs/interactionmanager/index.html @@ -16,7 +16,7 @@ InteractionManager · React Native - + @@ -30,7 +30,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/index.html b/docs/intro-react-native-components/index.html index f27c9f6db54..61101bc6712 100644 --- a/docs/intro-react-native-components/index.html +++ b/docs/intro-react-native-components/index.html @@ -16,7 +16,7 @@ Core Components and Native Components · React Native - + @@ -30,7 +30,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 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/intro-react/index.html b/docs/intro-react/index.html index c58d0795598..bc4b74ca0eb 100644 --- a/docs/intro-react/index.html +++ b/docs/intro-react/index.html @@ -16,7 +16,7 @@ React Fundamentals · React Native - + @@ -32,7 +32,7 @@
export default Cat;

You can export your function component with JavaScript’s export default for use throughout your app like so:

const Cat = () => {
return <Text>Hello, I am your cat!</Text>;
};
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/index.html b/docs/javascript-environment/index.html index 9dcd32950dc..09a8f08dd12 100644 --- a/docs/javascript-environment/index.html +++ b/docs/javascript-environment/index.html @@ -16,7 +16,7 @@ JavaScript Environment · React Native - + @@ -30,7 +30,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/index.html b/docs/keyboard/index.html index ec5c2a0a318..6dbc919234d 100644 --- a/docs/keyboard/index.html +++ b/docs/keyboard/index.html @@ -16,7 +16,7 @@ Keyboard · React Native - + @@ -30,7 +30,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/index.html b/docs/keyboardavoidingview/index.html index 87b29b09d00..9eada6bd862 100644 --- a/docs/keyboardavoidingview/index.html +++ b/docs/keyboardavoidingview/index.html @@ -16,7 +16,7 @@ KeyboardAvoidingView · React Native - + @@ -30,7 +30,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/index.html b/docs/layout-props/index.html index 026c3aac820..516e10b2a0e 100644 --- a/docs/layout-props/index.html +++ b/docs/layout-props/index.html @@ -16,7 +16,7 @@ Layout Props · React Native - + @@ -30,7 +30,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.

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/index.html b/docs/layoutanimation/index.html index 4ada8861ba6..13e216a1de2 100644 --- a/docs/layoutanimation/index.html +++ b/docs/layoutanimation/index.html @@ -16,7 +16,7 @@ LayoutAnimation · React Native - + @@ -30,7 +30,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/index.html b/docs/libraries/index.html index faf21eb8df7..d4302facb09 100644 --- a/docs/libraries/index.html +++ b/docs/libraries/index.html @@ -16,7 +16,7 @@ Using Libraries · React Native - + @@ -30,7 +30,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/index.html b/docs/linking-libraries-ios/index.html index 2ccb05fb0af..5397c93bb60 100644 --- a/docs/linking-libraries-ios/index.html +++ b/docs/linking-libraries-ios/index.html @@ -16,7 +16,7 @@ Linking Libraries · React Native - + @@ -30,7 +30,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/index.html b/docs/linking/index.html index e32bfd050c9..e10fe1c5177 100644 --- a/docs/linking/index.html +++ b/docs/linking/index.html @@ -16,7 +16,7 @@ Linking · React Native - + @@ -30,7 +30,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(url) -- 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/index.html b/docs/listview/index.html index 418e87c20a5..0a0dcc4c0f7 100644 --- a/docs/listview/index.html +++ b/docs/listview/index.html @@ -16,7 +16,7 @@ ListView · React Native - + @@ -31,7 +31,7 @@

ListView

DEPRECATED - use one of the new list components, such as FlatList or SectionList for bounded memory use, fewer bugs, better performance, an easier to use API, and more features. Check out this blog post for more details.

ListView - A core component designed for efficient display of vertically scrolling lists of changing data. The minimal API is to create a ListView.DataSource, populate it with a flat array of data blobs, and instantiate a ListView component with that data source and a renderRow callback which takes a blob from the data array and returns a renderable component.

Minimal example:

class MyComponent extends Component {
constructor() {
super();
const ds = new ListView.DataSource({
rowHasChanged: (r1, r2) => r1 !== r2
});
this.state = {
dataSource: ds.cloneWithRows(['row 1', 'row 2'])
};
}
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:

  • Only re-render changed rows - the rowHasChanged function provided to the data source tells the ListView if it needs to re-render a row because the source data has changed - see ListViewDataSource for more details.

  • Rate-limited row rendering - By default, only one row is rendered per event-loop (customizable with the pageSize prop). This breaks up the work into smaller chunks to reduce the chance of dropping frames while rendering rows.

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/index.html b/docs/listviewdatasource/index.html index 140a0517b9e..3ed3b8b93c7 100644 --- a/docs/listviewdatasource/index.html +++ b/docs/listviewdatasource/index.html @@ -16,7 +16,7 @@ ListViewDataSource · React Native - + @@ -30,7 +30,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/index.html b/docs/maskedviewios/index.html index 6b78cecd108..f6ac14449d3 100644 --- a/docs/maskedviewios/index.html +++ b/docs/maskedviewios/index.html @@ -16,7 +16,7 @@ 🚧 MaskedViewIOS · React Native - + @@ -31,7 +31,7 @@

🚧 MaskedViewIOS

Deprecated. Use @react-native-community/masked-view instead.

Renders the child view with a mask specified in the maskElement prop.

Example

import React from 'react';
import { MaskedViewIOS, Text, View } from 'react-native';
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/index.html b/docs/modal/index.html index 391897d5356..861317d917d 100644 --- a/docs/modal/index.html +++ b/docs/modal/index.html @@ -16,7 +16,7 @@ Modal · React Native - + @@ -30,7 +30,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/index.html b/docs/more-resources/index.html index 009f62f3f42..ae3cc5e42d5 100644 --- a/docs/more-resources/index.html +++ b/docs/more-resources/index.html @@ -16,7 +16,7 @@ More Resources · React Native - + @@ -30,7 +30,7 @@

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/native-components-android/index.html b/docs/native-components-android/index.html index 7eb80b0c106..ccf6a42f7fc 100644 --- a/docs/native-components-android/index.html +++ b/docs/native-components-android/index.html @@ -16,7 +16,7 @@ Native UI Components · React Native - + @@ -40,7 +40,7 @@
class MyCustomView extends React.Component {
constructor(props) {
super(props);
this._onChange = this._onChange.bind(this);
}
_onChange(event: Event) {
if (!this.props.onChangeMessage) {
return;
}
this.props.onChangeMessage(event.nativeEvent.message);
}
render() {
return <RCTMyCustomView {...this.props} onChange={this._onChange} />;
}
}
MyCustomView.propTypes = {
/**
* Callback that is called continuously when the user is dragging the map.
*/
onChangeMessage: PropTypes.func,
...
};
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
Edit this page
Last updated on
- + diff --git a/docs/native-components-ios/index.html b/docs/native-components-ios/index.html index cbefa616f9e..da5ddc1a078 100644 --- a/docs/native-components-ios/index.html +++ b/docs/native-components-ios/index.html @@ -16,7 +16,7 @@ Native UI Components · React Native - + @@ -93,7 +93,7 @@
- (NSDictionary *)constantsToExport
{
UIDatePicker *dp = [[UIDatePicker alloc] init];
[dp layoutIfNeeded];
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/index.html b/docs/native-modules-android/index.html index bd7fe7cd503..8121bb09dc7 100644 --- a/docs/native-modules-android/index.html +++ b/docs/native-modules-android/index.html @@ -16,7 +16,7 @@ Native Modules · React Native - + @@ -81,7 +81,7 @@
@Override
public void onHostPause() {
// Activity `onPause`
}
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}
Edit this page
Last updated on
- + diff --git a/docs/native-modules-ios/index.html b/docs/native-modules-ios/index.html index 21a234790ab..ffff080b5b9 100644 --- a/docs/native-modules-ios/index.html +++ b/docs/native-modules-ios/index.html @@ -16,7 +16,7 @@ Native Modules · React Native - + @@ -68,7 +68,7 @@
RCT_EXTERN_METHOD(addEvent:(NSString *)name location:(NSString *)location date:(nonnull NSNumber *)date)
@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/native-modules-setup/index.html b/docs/native-modules-setup/index.html index 72f5820afa3..90f1307e9d3 100644 --- a/docs/native-modules-setup/index.html +++ b/docs/native-modules-setup/index.html @@ -16,7 +16,7 @@ Native Modules Setup · React Native - + @@ -30,7 +30,7 @@

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 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/index.html b/docs/navigation/index.html index 4918e5c61ef..a1f7d9d67a3 100644 --- a/docs/navigation/index.html +++ b/docs/navigation/index.html @@ -16,7 +16,7 @@ Navigating Between Screens · React Native - + @@ -34,7 +34,7 @@
const Stack = createStackNavigator();
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 = () => {
return <Text>This is Jane'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/index.html b/docs/netinfo/index.html index 9846e6c5276..f16ac755b72 100644 --- a/docs/netinfo/index.html +++ b/docs/netinfo/index.html @@ -16,7 +16,7 @@ NetInfo · React Native - + @@ -30,7 +30,7 @@

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/network/index.html b/docs/network/index.html index 53ec4d2971f..57ff8f0b0c1 100644 --- a/docs/network/index.html +++ b/docs/network/index.html @@ -16,7 +16,7 @@ Networking · React Native - + @@ -36,7 +36,7 @@
ws.onerror = (e) => {
// an error occurred
console.log(e.message);
};
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

  • redirect:manual
  • credentials:omit
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 dabae2acf83..fbbef8743db 100644 --- a/docs/next/_getting-started-linux-android/index.html +++ b/docs/next/_getting-started-linux-android/index.html @@ -16,7 +16,7 @@ _getting-started-linux-android · React Native - + @@ -31,7 +31,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 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 intallation 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/next/_getting-started-macos-android/index.html b/docs/next/_getting-started-macos-android/index.html index c00d58b494b..da3aec36948 100644 --- a/docs/next/_getting-started-macos-android/index.html +++ b/docs/next/_getting-started-macos-android/index.html @@ -16,7 +16,7 @@ _getting-started-macos-android · React Native - + @@ -31,7 +31,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 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 cask install 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 intallation 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/next/_getting-started-macos-ios/index.html b/docs/next/_getting-started-macos-ios/index.html index 87d61c69eae..34bd5153291 100644 --- a/docs/next/_getting-started-macos-ios/index.html +++ b/docs/next/_getting-started-macos-ios/index.html @@ -16,7 +16,7 @@ _getting-started-macos-ios · React Native - + @@ -31,7 +31,7 @@
Version: Next

_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/next/_getting-started-windows-android/index.html b/docs/next/_getting-started-windows-android/index.html index 22fd15dfef8..77188ce8443 100644 --- a/docs/next/_getting-started-windows-android/index.html +++ b/docs/next/_getting-started-windows-android/index.html @@ -16,7 +16,7 @@ _getting-started-windows-android · React Native - + @@ -31,7 +31,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.

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 intallation 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/next/_integration-with-exisiting-apps-java/index.html b/docs/next/_integration-with-exisiting-apps-java/index.html index 9d4d274a84e..a91e7687d76 100644 --- a/docs/next/_integration-with-exisiting-apps-java/index.html +++ b/docs/next/_integration-with-exisiting-apps-java/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-java · React Native - + @@ -45,7 +45,7 @@
@Override
protected void onDestroy() {
super.onDestroy();
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/index.html b/docs/next/_integration-with-exisiting-apps-objc/index.html index 9b13d8bf19c..ffc3f31e1a6 100644 --- a/docs/next/_integration-with-exisiting-apps-objc/index.html +++ b/docs/next/_integration-with-exisiting-apps-objc/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-objc · React Native - + @@ -39,7 +39,7 @@
// Module name
AppRegistry.registerComponent('RNHighScores', () => RNHighScores);

RNHighScores is the name of your module that will be used when you add a view to React Native from within your iOS application.

The Magic: RCTRootView

Now that your React Native component is created via index.js, you need to add that component to a new or existing ViewController. The easiest path to take is to optionally create an event path to your component and then add that component to an existing ViewController.

We will tie our React Native component with a new native view in the ViewController that will actually contain it called RCTRootView .

1. Create an Event Path

You can add a new link on the main game menu to go to the "High Score" React Native page.

Event Path

2. Event Handler

We will now add an event handler from the menu link. A method will be added to the main ViewController of your application. This is where RCTRootView comes into play.

When you build a React Native application, you use the Metro bundler to create an index.bundle that will be served by the React Native server. Inside index.bundle will be our RNHighScore module. So, we need to point our RCTRootView to the location of the index.bundle resource (via NSURL) and tie it to the module.

We will, for debugging purposes, log that the event handler was invoked. Then, we will create a string with the location of our React Native code that exists inside the index.bundle. Finally, we will create the main RCTRootView. Notice how we provide RNHighScores as the moduleName that we created above when writing the code for our React Native component.

First import the RCTRootView header.

#import <React/RCTRootView.h>

The initialProperties are here for illustration purposes so we have some data for our high score screen. In our React Native component, we will use this.props to get access to that data.

- (IBAction)highScoreButtonPressed:(id)sender {
NSLog(@"High Score Button Pressed");
NSURL *jsCodeLocation = [NSURL URLWithString:@"http://localhost:8081/index.bundle?platform=ios"];
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/index.html b/docs/next/_integration-with-exisiting-apps-swift/index.html index 9474f11e69c..2ff89e351ea 100644 --- a/docs/next/_integration-with-exisiting-apps-swift/index.html +++ b/docs/next/_integration-with-exisiting-apps-swift/index.html @@ -16,7 +16,7 @@ _integration-with-exisiting-apps-swift · React Native - + @@ -39,7 +39,7 @@
// Module name
AppRegistry.registerComponent('RNHighScores', () => RNHighScores);

RNHighScores is the name of your module that will be used when you add a view to React Native from within your iOS application.

The Magic: RCTRootView

Now that your React Native component is created via index.js, you need to add that component to a new or existing ViewController. The easiest path to take is to optionally create an event path to your component and then add that component to an existing ViewController.

We will tie our React Native component with a new native view in the ViewController that will actually contain it called RCTRootView .

1. Create an Event Path

You can add a new link on the main game menu to go to the "High Score" React Native page.

Event Path

2. Event Handler

We will now add an event handler from the menu link. A method will be added to the main ViewController of your application. This is where RCTRootView comes into play.

When you build a React Native application, you use the Metro bundler to create an index.bundle that will be served by the React Native server. Inside index.bundle will be our RNHighScore module. So, we need to point our RCTRootView to the location of the index.bundle resource (via NSURL) and tie it to the module.

We will, for debugging purposes, log that the event handler was invoked. Then, we will create a string with the location of our React Native code that exists inside the index.bundle. Finally, we will create the main RCTRootView. Notice how we provide RNHighScores as the moduleName that we created above when writing the code for our React Native component.

First import the React library.

import React

The initialProperties are here for illustration purposes so we have some data for our high score screen. In our React Native component, we will use this.props to get access to that data.

@IBAction func highScoreButtonTapped(sender : UIButton) {
NSLog("Hello")
let jsCodeLocation = URL(string: "http://localhost:8081/index.bundle?platform=ios")
let mockData:NSDictionary = ["scores":
[
["name":"Alex", "value":"42"],
["name":"Joel", "value":"10"]
]
]
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/index.html b/docs/next/accessibility/index.html index a7eabb9a8cb..47216ecc321 100644 --- a/docs/next/accessibility/index.html +++ b/docs/next/accessibility/index.html @@ -16,7 +16,7 @@ Accessibility · React Native - + @@ -32,7 +32,7 @@
if (Platform.OS === 'android') {
UIManager.sendAccessibilityEvent(
findNodeHandle(this),
UIManager.AccessibilityEventTypes.typeViewFocused
);
}

Testing TalkBack Support
Android

To enable TalkBack, go to the Settings app on your Android device or emulator. Tap Accessibility, then TalkBack. Toggle the "Use service" switch to enable or disable it.

P.S. Android emulator doesn’t have TalkBack by default. To install it:

  1. Download TalkBack file here: https://google-talkback.en.uptodown.com/android
  2. Drag the downloaded .apk file into the emulator

You can use the volume key shortcut to toggle TalkBack. To turn on the volume key shortcut, go to the Settings app, then Accessibility. At the top, turn on Volume key shortcut.

To use the volume key shortcut, press both volume keys for 3 seconds to start an accessibility tool.

Additionally, if you prefer, you can toggle TalkBack via command line with:

# disable
adb shell settings put secure enabled_accessibility_services com.android.talkback/com.google.android.marvin.talkback.TalkBackService
# 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/index.html b/docs/next/accessibilityinfo/index.html index 691f538696a..1fad2fa80c0 100644 --- a/docs/next/accessibilityinfo/index.html +++ b/docs/next/accessibilityinfo/index.html @@ -16,7 +16,7 @@ AccessibilityInfo · React Native - + @@ -30,7 +30,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

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/next/actionsheetios/index.html b/docs/next/actionsheetios/index.html index 7923715dd80..531741d71d8 100644 --- a/docs/next/actionsheetios/index.html +++ b/docs/next/actionsheetios/index.html @@ -16,7 +16,7 @@ ActionSheetIOS · React Native - + @@ -30,7 +30,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

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/index.html b/docs/next/activityindicator/index.html index 9201c88cb39..65e9d1eb9cc 100644 --- a/docs/next/activityindicator/index.html +++ b/docs/next/activityindicator/index.html @@ -16,7 +16,7 @@ ActivityIndicator · React Native - + @@ -30,7 +30,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/index.html b/docs/next/alert/index.html index 4361a99b983..ffce319fa74 100644 --- a/docs/next/alert/index.html +++ b/docs/next/alert/index.html @@ -16,7 +16,7 @@ Alert · React Native - + @@ -30,7 +30,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 avaiable on iOS only.

Example

iOS

On iOS you can specify any number of buttons. Each button can optionally specify a style, avaiable 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
titlestring
Required
The 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 containg buttons configuration.
optionsOptions
Android
An 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
titlestring
Required
The 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/index.html b/docs/next/alertios/index.html index 5a67c6346a9..1a44ffcac2d 100644 --- a/docs/next/alertios/index.html +++ b/docs/next/alertios/index.html @@ -16,7 +16,7 @@ 🚧 AlertIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/next/animated/index.html index 3de8ed19bd3..f9749d88e61 100644 --- a/docs/next/animated/index.html +++ b/docs/next/animated/index.html @@ -16,7 +16,7 @@ Animated · React Native - + @@ -30,7 +30,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/index.html b/docs/next/animatedvalue/index.html index 1db3af75a78..263029e51f1 100644 --- a/docs/next/animatedvalue/index.html +++ b/docs/next/animatedvalue/index.html @@ -16,7 +16,7 @@ Animated.Value · React Native - + @@ -30,7 +30,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/index.html b/docs/next/animatedvaluexy/index.html index d8863448e5f..dee06a4b6eb 100644 --- a/docs/next/animatedvaluexy/index.html +++ b/docs/next/animatedvaluexy/index.html @@ -16,7 +16,7 @@ Animated.ValueXY · React Native - + @@ -30,7 +30,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/index.html b/docs/next/animations/index.html index 5cad25a3586..691d444e255 100644 --- a/docs/next/animations/index.html +++ b/docs/next/animations/index.html @@ -16,7 +16,7 @@ Animations · React Native - + @@ -31,7 +31,7 @@
Version: Next

Animations

Animations are very important to create a great user experience. Stationary objects must overcome inertia as they start moving. Objects in motion have momentum and rarely come to a stop immediately. Animations allow you to convey physically believable motion in your interface.

React Native provides two complementary animation systems: Animated for granular and interactive control of specific values, and LayoutAnimation for animated global layout transactions.

Animated API

The Animated API is designed to concisely express a wide variety of interesting animation and interaction patterns in a very performant way. Animated focuses on declarative relationships between inputs and outputs, with configurable transforms in between, and start/stop methods to control time-based animation execution.

Animated exports six animatable component types: View, Text, Image, ScrollView, FlatList and SectionList, but you can also create your own using Animated.createAnimatedComponent().

For example, a container view that fades in when it is mounted may look like this:

Let's break down what's happening here. In the FadeInView constructor, a new Animated.Value called fadeAnim is initialized as part of state. The opacity property on the View is mapped to this animated value. Behind the scenes, the numeric value is extracted and used to set opacity.

When the component mounts, the opacity is set to 0. Then, an easing animation is started on the fadeAnim animated value, which will update all of its dependent mappings (in this case, only the opacity) on each frame as the value animates to the final value of 1.

This is done in an optimized way that is faster than calling setState and re-rendering. Because the entire configuration is declarative, we will be able to implement further optimizations that serialize the configuration and runs the animation on a high-priority thread.

Configuring animations

Animations are heavily configurable. Custom and predefined easing functions, delays, durations, decay factors, spring constants, and more can all be tweaked depending on the type of animation.

Animated provides several animation types, the most commonly used one being Animated.timing(). It supports animating a value over time using one of various predefined easing functions, or you can use your own. Easing functions are typically used in animation to convey gradual acceleration and deceleration of objects.

By default, timing will use an easeInOut curve that conveys gradual acceleration to full speed and concludes by gradually decelerating to a stop. You can specify a different easing function by passing an easing parameter. Custom duration or even a delay before the animation starts is also supported.

For example, if we want to create a 2-second long animation of an object that slightly backs up before moving to its final position:

Animated.timing(this.state.xPosition, {
toValue: 100,
easing: Easing.back(),
duration: 2000
}).start();

Take a look at the Configuring animations section of the Animated API reference to learn more about all the config parameters supported by the built-in animations.

Composing animations

Animations can be combined and played in sequence or in parallel. Sequential animations can play immediately after the previous animation has finished, or they can start after a specified delay. The Animated API provides several methods, such as sequence() and delay(), each of which take an array of animations to execute and automatically calls start()/stop() as needed.

For example, the following animation coasts to a stop, then it springs back while twirling in parallel:

Animated.sequence([
// decay, then spring to start and twirl
Animated.decay(position, {
// coast to a stop
velocity: { x: gestureState.vx, y: gestureState.vy }, // velocity from gesture release
deceleration: 0.997
}),
Animated.parallel([
// after decay, in parallel:
Animated.spring(position, {
toValue: { x: 0, y: 0 } // return to start
}),
Animated.timing(twirl, {
// and twirl
toValue: 360
})
])
]).start(); // start the sequence group

If one animation is stopped or interrupted, then all other animations in the group are also stopped. Animated.parallel has a stopTogether option that can be set to false to disable this.

You can find a full list of composition methods in the Composing animations section of the Animated API reference.

Combining animated values

You can combine two animated values via addition, multiplication, division, or modulo to make a new animated value.

There are some cases where an animated value needs to invert another animated value for calculation. An example is inverting a scale (2x --> 0.5x):

const a = new Animated.Value(1);
const b = Animated.divide(1, a);
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:

  • spring.stopAnimation(callback) will stop the animation and invoke callback with the final value. This is useful when making gesture transitions.
  • spring.addListener(callback) will invoke callback asynchronously while the animation is running, providing a recent value. This is useful for triggering state changes, for example snapping a bobble to a new option as the user drags it closer, because these larger state changes are less sensitive to a few frames of lag compared to continuous gestures like panning which need to run at 60 fps.

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/index.html b/docs/next/app-extensions/index.html index 473d79d3341..6d9d813ed87 100644 --- a/docs/next/app-extensions/index.html +++ b/docs/next/app-extensions/index.html @@ -16,7 +16,7 @@ App Extensions · React Native - + @@ -30,7 +30,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/index.html b/docs/next/appearance/index.html index c22ac7d02fd..09b5f5292ea 100644 --- a/docs/next/appearance/index.html +++ b/docs/next/appearance/index.html @@ -16,7 +16,7 @@ Appearance · React Native - + @@ -30,7 +30,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/index.html b/docs/next/appregistry/index.html index 06d0719af5e..98e8795184a 100644 --- a/docs/next/appregistry/index.html +++ b/docs/next/appregistry/index.html @@ -16,7 +16,7 @@ AppRegistry · React Native - + @@ -32,7 +32,7 @@
const App = (props) => (
<View>
<Text>App1</Text>
</View>
);
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/index.html b/docs/next/appstate/index.html index ba67ba4ac22..60d965dec7d 100644 --- a/docs/next/appstate/index.html +++ b/docs/next/appstate/index.html @@ -16,7 +16,7 @@ AppState · React Native - + @@ -30,7 +30,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/index.html b/docs/next/asyncstorage/index.html index 1ce9696b61e..86eb383c7f0 100644 --- a/docs/next/asyncstorage/index.html +++ b/docs/next/asyncstorage/index.html @@ -16,7 +16,7 @@ 🚧 AsyncStorage · React Native - + @@ -38,7 +38,7 @@
AsyncStorage.multiSet(multi_set_pairs, (err) => {
AsyncStorage.multiMerge(multi_merge_pairs, (err) => {
AsyncStorage.multiGet(['UID234', 'UID345'], (err, stores) => {
stores.map((result, i, store) => {
let key = store[i][0];
let val = store[i][1];
console.log(key, val);
});
});
});
});
// 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/index.html b/docs/next/backhandler/index.html index 39251ad37f6..09eb4c4ed41 100644 --- a/docs/next/backhandler/index.html +++ b/docs/next/backhandler/index.html @@ -16,7 +16,7 @@ BackHandler · React Native - + @@ -31,7 +31,7 @@
Version: Next

BackHandler

The Backhandler API detects hardware button presses for back navigation, lets you register event listeners for the system's back action, and lets you control how your application responds. It is Android-only.

The event subscriptions are called in reverse order (i.e. the last registered subscription is called first).

  • If one subscription returns true, then subscriptions registered earlier will not be called.
  • If no subscription returns true or none are registered, it programmatically invokes the default back button functionality to exit the app.

Warning for modal users: If your app shows an opened Modal, BackHandler will not publish any events (see Modal docs).

Pattern

BackHandler.addEventListener('hardwareBackPress', function() {
/**
* this.onMainScreen and this.goBack are just examples,
* you need to use your own implementation here.
*
* Typically you would use the navigator here to go to the last state.
*/
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/index.html b/docs/next/building-for-tv/index.html index 2ff410ea8b8..29096c4f799 100644 --- a/docs/next/building-for-tv/index.html +++ b/docs/next/building-for-tv/index.html @@ -16,7 +16,7 @@ Building For TV Devices · React Native - + @@ -35,7 +35,7 @@
componentDidMount() {
this._enableTVEventHandler();
}
componentWillUnmount() {
this._disableTVEventHandler();
}
}

  • Dev Menu support: On the emulator, cmd-M will bring up the developer menu, similar to Android. To bring it up on a real Android TV device, press the menu button or long press the fast-forward button on the remote. (Please do not shake the Android TV device, that will not work :) )

  • Known issues:

    • TextInput components do not work for now (i.e. they cannot receive focus automatically, see this comment).
      • It is however possible to use a ref to manually trigger inputRef.current.focus().
      • You can wrap your input inside a TouchableWithoutFeedback component and trigger focus in the onFocus event of that touchable. This enables opening the keyboard via the arrow keys.
      • The keyboard might reset its state after each keypress (this might only happen inside the Android TV emulator).
    • The content of Modal components cannot receive focus, see this issue for details.
Edit this page
Last updated on
- + diff --git a/docs/next/button/index.html b/docs/next/button/index.html index a896f267400..67f04e3ff1f 100644 --- a/docs/next/button/index.html +++ b/docs/next/button/index.html @@ -16,7 +16,7 @@ Button · React Native - + @@ -30,7 +30,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/index.html b/docs/next/checkbox/index.html index 1a3bc3ce437..ee2e9dcbc27 100644 --- a/docs/next/checkbox/index.html +++ b/docs/next/checkbox/index.html @@ -16,7 +16,7 @@ 🚧 CheckBox · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 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/next/clipboard/index.html b/docs/next/clipboard/index.html index 257518564f3..1f4cad04475 100644 --- a/docs/next/clipboard/index.html +++ b/docs/next/clipboard/index.html @@ -16,7 +16,7 @@ 🚧 Clipboard · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 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/next/colors/index.html b/docs/next/colors/index.html index 0c89d67d64b..7fade66bde6 100644 --- a/docs/next/colors/index.html +++ b/docs/next/colors/index.html @@ -16,7 +16,7 @@ Color Reference · React Native - + @@ -30,7 +30,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/index.html b/docs/next/communication-android/index.html index 1c76b9757c2..a66abc73b1e 100644 --- a/docs/next/communication-android/index.html +++ b/docs/next/communication-android/index.html @@ -16,7 +16,7 @@ Communication between native and React Native · React Native - + @@ -32,7 +32,7 @@
export default class ImageBrowserApp extends React.Component {
renderImage(imgURI) {
return <Image source={{ uri: imgURI }} />;
}
render() {
return <View>{this.props.images.map(this.renderImage)}</View>;
}
}

ReactRootView provides a read-write property appProperties. After appProperties is set, the React Native app is re-rendered with new properties. The update is only performed when the new updated properties differ from the previous ones.

Bundle updatedProps = mReactRootView.getAppProperties();
ArrayList<String> imageList = new ArrayList<String>(Arrays.asList(
"http://foo.com/bar3.png",
"http://foo.com/bar4.png"
));
updatedProps.putStringArrayList("images", imageList);
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:

  • As events can be sent from anywhere, they can introduce spaghetti-style dependencies into your project.
  • Events share namespace, which means that you may encounter some name collisions. Collisions will not be detected statically, which makes them hard to debug.
  • If you use several instances of the same React Native component and you want to distinguish them from the perspective of your event, you'll likely need to introduce identifiers and pass them along with events (you can use the native view's reactTag as an identifier).

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/index.html b/docs/next/communication-ios/index.html index bea6d7da326..b66e3e13911 100644 --- a/docs/next/communication-ios/index.html +++ b/docs/next/communication-ios/index.html @@ -16,7 +16,7 @@ Communication between native and React Native · React Native - + @@ -41,7 +41,7 @@
#pragma mark - RCTRootViewDelegate
- (void)rootViewDidChangeIntrinsicSize:(RCTRootView *)rootView
{
CGRect newFrame = rootView.frame;
newFrame.size = rootView.intrinsicContentSize;
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/index.html b/docs/next/components-and-apis/index.html index f5894496d28..c3fcf95d993 100644 --- a/docs/next/components-and-apis/index.html +++ b/docs/next/components-and-apis/index.html @@ -16,7 +16,7 @@ Core Components and APIs · React Native - + @@ -30,7 +30,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.

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/next/custom-webview-android/index.html b/docs/next/custom-webview-android/index.html index 4a00c48a273..5fbb886667e 100644 --- a/docs/next/custom-webview-android/index.html +++ b/docs/next/custom-webview-android/index.html @@ -16,7 +16,7 @@ Custom WebView · React Native - + @@ -57,7 +57,7 @@
_onNavigationCompleted = (event) => {
const { onNavigationCompleted } = this.props;
onNavigationCompleted && onNavigationCompleted(event);
};
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/index.html b/docs/next/custom-webview-ios/index.html index f02d2ed1bc4..a5a66e33138 100644 --- a/docs/next/custom-webview-ios/index.html +++ b/docs/next/custom-webview-ios/index.html @@ -16,7 +16,7 @@ Custom WebView · React Native - + @@ -60,7 +60,7 @@
_onNavigationCompleted = (event) => {
const { onNavigationCompleted } = this.props;
onNavigationCompleted && onNavigationCompleted(event);
};
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/index.html b/docs/next/datepickerandroid/index.html index 4e197355d20..00f7168bf01 100644 --- a/docs/next/datepickerandroid/index.html +++ b/docs/next/datepickerandroid/index.html @@ -16,7 +16,7 @@ 🚧 DatePickerAndroid · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 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/next/datepickerios/index.html b/docs/next/datepickerios/index.html index 149a2c66035..6d63c0457f6 100644 --- a/docs/next/datepickerios/index.html +++ b/docs/next/datepickerios/index.html @@ -16,7 +16,7 @@ 🚧 DatePickerIOS · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 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/next/debugging/index.html b/docs/next/debugging/index.html index 8c4bb619924..c0ce5d8176a 100644 --- a/docs/next/debugging/index.html +++ b/docs/next/debugging/index.html @@ -16,7 +16,7 @@ Debugging · React Native - + @@ -32,7 +32,7 @@
// Ignore log notification by message:
LogBox.ignoreLogs(['Warning: ...']);
// 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".

  • 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/next/devsettings/index.html b/docs/next/devsettings/index.html index 5cf2efab884..7c1b62f05af 100644 --- a/docs/next/devsettings/index.html +++ b/docs/next/devsettings/index.html @@ -16,7 +16,7 @@ DevSettings · React Native - + @@ -30,7 +30,7 @@
Version: Next

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/next/dimensions/index.html b/docs/next/dimensions/index.html index b5b25b4d6bc..6edf5de029a 100644 --- a/docs/next/dimensions/index.html +++ b/docs/next/dimensions/index.html @@ -16,7 +16,7 @@ Dimensions · React Native - + @@ -30,7 +30,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/index.html b/docs/next/direct-manipulation/index.html index cc2d866b82b..66651ad0eeb 100644 --- a/docs/next/direct-manipulation/index.html +++ b/docs/next/direct-manipulation/index.html @@ -16,7 +16,7 @@ Direct Manipulation · React Native - + @@ -30,7 +30,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/index.html b/docs/next/drawerlayoutandroid/index.html index d3e6b477303..2e3e1487cac 100644 --- a/docs/next/drawerlayoutandroid/index.html +++ b/docs/next/drawerlayoutandroid/index.html @@ -16,7 +16,7 @@ DrawerLayoutAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/next/dynamiccolorios/index.html index 93fbc96c57e..2f98f2416c7 100644 --- a/docs/next/dynamiccolorios/index.html +++ b/docs/next/dynamiccolorios/index.html @@ -16,7 +16,7 @@ DynamicColorIOS · React Native - + @@ -31,7 +31,7 @@
Version: Next

DynamicColorIOS

The DynamicColorIOS function is a platform color type specific to iOS.

DynamicColorIOS({ light: color, dark: color });

DynamicColorIOS takes a single argument as an object with two keys: dark and light. These correspond to the colors you want to use for "light mode" and "dark mode" on iOS.

In the future, more keys might become available for different user preferences, like high contrast.

At runtime, the system will choose which of the two colors to display depending on the current system appearance settings. Dynamic colors are useful for branding colors or other app specific colors that still respond automatically to system setting changes.

Developer notes

If you’re familiar with @media (prefers-color-scheme: dark) in CSS, this is similar! Only instead of defining all the colors in a media query, you define which color to use under what circumstances right there where you're using it. Neat!

Example

import { DynamicColorIOS } from 'react-native';
const customDynamicTextColor = DynamicColorIOS({
dark: 'lightskyblue',
light: 'midnightblue'
});
Edit this page
Last updated on
- + diff --git a/docs/next/easing/index.html b/docs/next/easing/index.html index b313f2438a7..a3f31c1128d 100644 --- a/docs/next/easing/index.html +++ b/docs/next/easing/index.html @@ -16,7 +16,7 @@ Easing · React Native - + @@ -30,7 +30,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/index.html b/docs/next/environment-setup/index.html index 06a454a7774..0daf4f459bf 100644 --- a/docs/next/environment-setup/index.html +++ b/docs/next/environment-setup/index.html @@ -16,7 +16,7 @@ Setting up the development environment · React Native - + @@ -32,7 +32,7 @@
Version: Next

Setting up the development environment

This page will help you install and build your first React Native app.

If you are new to mobile development, the easiest way to get started is with Expo CLI. Expo is a set of tools built around React Native and, while it has many features, the most relevant feature for us right now is that it can get you writing a React Native app within minutes. You will only need a recent version of Node.js and a phone or emulator. If you'd like to try out React Native directly in your web browser before installing any tools, you can try out Snack.

If you are already familiar with mobile development, you may want to use React Native CLI. It requires Xcode or Android Studio to get started. If you already have one of these tools installed, you should be able to get up and running within a few minutes. If they are not installed, you should expect to spend about an hour installing and configuring them.

Assuming that you have Node 12 LTS or greater installed, you can use npm to install the Expo CLI command line utility:

npm install -g expo-cli

Then run the following commands to create a new React Native project called "AwesomeProject":

expo init AwesomeProject
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/index.html b/docs/next/fast-refresh/index.html index a04ae1544e3..d9c42e9d700 100644 --- a/docs/next/fast-refresh/index.html +++ b/docs/next/fast-refresh/index.html @@ -16,7 +16,7 @@ Fast Refresh · React Native - + @@ -30,7 +30,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/index.html b/docs/next/flatlist/index.html index 06be1791b36..c5341bd9045 100644 --- a/docs/next/flatlist/index.html +++ b/docs/next/flatlist/index.html @@ -16,7 +16,7 @@ FlatList · React Native - + @@ -31,7 +31,7 @@
Version: Next

FlatList

A performant interface for rendering basic, flat lists, supporting the most handy features:

  • Fully cross-platform.
  • Optional horizontal mode.
  • Configurable viewability callbacks.
  • Header support.
  • Footer support.
  • Separator support.
  • Pull to Refresh.
  • Scroll loading.
  • ScrollToIndex support.
  • Multiple column support.

If you need section support, use <SectionList>.

Example

To render multiple columns, use the numColumns prop. Using this approach instead of a flexWrap layout can prevent conflicts with the item height logic.

More complex, selectable example below.

  • By passing extraData={selectedId} to FlatList we make sure FlatList itself will re-render when the state changes. Without setting this prop, FlatList would not know it needs to re-render any items because it is a PureComponent and the prop comparison will not show any changes.
  • keyExtractor tells the list to use the ids for the react keys instead of the default key property.

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, unless it is nested in another FlatList of same orientation.

renderItem

renderItem({ item, index, separators });

Takes an item from data and renders it into the list.

Provides additional metadata like index if you need it, as well as a more generic separators.updateProps function which let you set whatever props you want to change the rendering of either the leading separator or trailing separator in case the more common highlight and unhighlight (which set the highlighted: boolean prop) are insufficient for your use case.

TypeRequired
functionYes
  • item (Object): The item from data being rendered.
  • index (number): The index corresponding to this item in the data array.
  • separators (Object)
    • highlight (Function)
    • unhighlight (Function)
    • updateProps (Function)
      • select (enum('leading', 'trailing'))
      • newProps (Object)

Example usage:

<FlatList
ItemSeparatorComponent={
Platform.OS !== 'android' &&
(({ highlighted }) => (
<View
style={[
style.separator,
highlighted && { marginLeft: 0 }
]}
/>
))
}
data={[{ title: 'Title Text', key: 'item1' }]}
renderItem={({ item, index, separators }) => (
<TouchableHighlight
key={item.key}
onPress={() => this._onPress(item)}
onShowUnderlay={separators.highlight}
onHideUnderlay={separators.unhighlight}>
<View style={{ backgroundColor: 'white' }}>
<Text>{item.title}</Text>
</View>
</TouchableHighlight>
)}
/>

data

For simplicity, data is a plain array. If you want to use something else, like an immutable list, use the underlying VirtualizedList directly.

TypeRequired
arrayYes

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted and leadingItem 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
componentNo

ListEmptyComponent

Rendered when the list is empty. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListFooterComponent

Rendered at the bottom of all the items. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListFooterComponentStyle

Styling for internal View for ListFooterComponent

TypeRequired
style objectNo

ListHeaderComponent

Rendered at the top of all the items. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, elementNo

ListHeaderComponentStyle

Styling for internal View for ListHeaderComponent

TypeRequired
style objectNo

columnWrapperStyle

Optional custom style for multi-item rows generated when numColumns > 1.

TypeRequired
style objectNo

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, index) => {length: number, offset: number, index: number}

getItemLayout is an optional optimization that allows skipping the measurement of dynamic content if you know the size (height or width) of items ahead of time. getItemLayout is efficient if you have fixed size items, for example:

getItemLayout={(data, index) => (
{length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index}
)}

Adding getItemLayout can be a great performance boost for lists of several hundred items. Remember to include separator length (height or width) in your offset calculation if you specify ItemSeparatorComponent.

TypeRequired
functionNo

horizontal

If true, renders items next to each other horizontally instead of stacked vertically.

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

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

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 falls back to using the index, like React does.

TypeRequired
functionNo

numColumns

Multiple columns can only be rendered with horizontal={false} and will zig-zag like a flexWrap layout. Items should all be the same height - masonry layouts are not supported.

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

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

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

progressViewOffset

Set this when offset is needed for the loading indicator to show correctly.

TypeRequiredPlatform
numberNoAndroid

legacyImplementation

May not have full feature parity and is meant for debugging and performance comparison.

TypeRequired
booleanNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
booleanNo

removeClippedSubviews

This may improve scroll performance for large lists. On Android the default value is true

Note: May have bugs (missing content) in some circumstances - use at your own risk.

TypeRequired
booleanNo

viewabilityConfig

See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
ViewabilityConfigNo

viewabilityConfig takes a type ViewabilityConfig an object with following properties

PropertyRequiredType
minimumViewTimeNonumber
viewAreaCoveragePercentThresholdNonumber
itemVisiblePercentThresholdNonumber
waitForInteractionNoboolean

At least one of the viewAreaCoveragePercentThreshold or itemVisiblePercentThreshold is required. This needs to be done in the constructor to avoid following error (ref):

Error: Changing viewabilityConfig on the fly is not supported`
constructor (props) {
super(props)
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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.

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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'index' (number) - The index to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position.
  • '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.

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:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'item' (object) - The item to scroll to. Required.
  • 'viewPosition' (number)

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'offset' (number) - The offset to scroll to. In case of horizontal being true, the offset is the x-value, in any other case the offset is the y-value. Required.
  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.

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/next/flexbox/index.html b/docs/next/flexbox/index.html index a53a79a0598..94df9ff471d 100644 --- a/docs/next/flexbox/index.html +++ b/docs/next/flexbox/index.html @@ -16,7 +16,7 @@ Layout with Flexbox · React Native - + @@ -30,7 +30,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, 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 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 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.

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

  • 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.

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/index.html b/docs/next/gesture-responder-system/index.html index 1a30ebceb90..f895d46e3f6 100644 --- a/docs/next/gesture-responder-system/index.html +++ b/docs/next/gesture-responder-system/index.html @@ -16,7 +16,7 @@ Gesture Responder System · React Native - + @@ -30,7 +30,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/index.html b/docs/next/getting-started/index.html index d65523b1639..db8e4ecfb22 100644 --- a/docs/next/getting-started/index.html +++ b/docs/next/getting-started/index.html @@ -16,7 +16,7 @@ Introduction · React Native - + @@ -30,7 +30,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/index.html b/docs/next/handling-text-input/index.html index 688b4c0c15f..2b9cbb7534c 100644 --- a/docs/next/handling-text-input/index.html +++ b/docs/next/handling-text-input/index.html @@ -16,7 +16,7 @@ Handling Text Input · React Native - + @@ -30,7 +30,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/index.html b/docs/next/handling-touches/index.html index e8932ff443f..8a6c08f473c 100644 --- a/docs/next/handling-touches/index.html +++ b/docs/next/handling-touches/index.html @@ -16,7 +16,7 @@ Handling Touches · React Native - + @@ -30,7 +30,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, 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/next/headless-js-android/index.html b/docs/next/headless-js-android/index.html index 28e9e789ec1..3b512f48808 100644 --- a/docs/next/headless-js-android/index.html +++ b/docs/next/headless-js-android/index.html @@ -16,7 +16,7 @@ Headless JS · React Native - + @@ -41,7 +41,7 @@
}
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 cb27e8c10be..c358a512268 100644 --- a/docs/next/height-and-width/index.html +++ b/docs/next/height-and-width/index.html @@ -16,7 +16,7 @@ Height and Width · React Native - + @@ -30,7 +30,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/index.html b/docs/next/hermes/index.html index 9433bfe5ee5..48b4b728c99 100644 --- a/docs/next/hermes/index.html +++ b/docs/next/hermes/index.html @@ -16,7 +16,7 @@ Using Hermes · React Native - + @@ -30,7 +30,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 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 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/next/image-style-props/index.html b/docs/next/image-style-props/index.html index 78be32fd13f..114f5dda4c6 100644 --- a/docs/next/image-style-props/index.html +++ b/docs/next/image-style-props/index.html @@ -16,7 +16,7 @@ Image Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/next/image/index.html index 3ec2cce56ed..1d47cc13441 100644 --- a/docs/next/image/index.html +++ b/docs/next/image/index.html @@ -16,7 +16,7 @@ Image · React Native - + @@ -33,7 +33,7 @@
// For WebP support, including animated WebP
implementation 'com.facebook.fresco:animated-webp:2.1.0'
implementation 'com.facebook.fresco:webpsupport:2.0.0'
// 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}:

  • 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 (which should be wrapped in the require('./path/to/image.png') function).
  • width, height - can be specified if known at build time, in which case these will be used to set the default <Image/> component dimensions.
  • scale - used 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.

If passing a number:

  • number - Opaque type returned by something like require('./image.jpg').

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 on layout changes.

TypeRequired
(LayoutEvent) => voidNo

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.

  • auto: Use heuristics to pick between resize and scale.

  • resize: A software operation which changes the encoded image in memory before it gets decoded. This should be used instead of scale when the image is much larger than the view.

  • scale: The image gets drawn downscaled or upscaled. Compared to resize, scale is faster (usually hardware accelerated) and produces higher quality images. This should be used if the image is smaller than the view. It should also be used if the image is slightly bigger than the view.

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.

  • cover: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or larger than the corresponding dimension of the view (minus padding).

  • contain: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or less than the corresponding dimension of the view (minus padding).

  • stretch: Scale width and height independently, This may change the aspect ratio of the src.

  • repeat: Repeat the image to cover the frame of the view. The image will keep its size and aspect ratio, unless it is larger than the view, in which case it will be scaled down uniformly so that it is contained in the view.

  • center: Center the image in the view along both dimensions. If the image is larger than the view, scale it down uniformly so that it is contained in the view.

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 to 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/next/imagebackground/index.html b/docs/next/imagebackground/index.html index d8b099c0f62..699b858722e 100644 --- a/docs/next/imagebackground/index.html +++ b/docs/next/imagebackground/index.html @@ -16,7 +16,7 @@ ImageBackground · React Native - + @@ -30,7 +30,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/index.html b/docs/next/imageeditor/index.html index fa67057b313..e8965f20fb7 100644 --- a/docs/next/imageeditor/index.html +++ b/docs/next/imageeditor/index.html @@ -16,7 +16,7 @@ 🚧 ImageEditor · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 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/next/imagepickerios/index.html b/docs/next/imagepickerios/index.html index bc8f014e47a..19da40c6ce7 100644 --- a/docs/next/imagepickerios/index.html +++ b/docs/next/imagepickerios/index.html @@ -16,7 +16,7 @@ 🚧 ImagePickerIOS · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 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/next/images/index.html b/docs/next/images/index.html index 9f5b8c7ecdc..1adacc4d961 100644 --- a/docs/next/images/index.html +++ b/docs/next/images/index.html @@ -16,7 +16,7 @@ Images · React Native - + @@ -33,7 +33,7 @@
// GOOD
var icon = this.props.active
? require('./my-icon-active.png')
: require('./my-icon-inactive.png');
<Image source={icon} />;

Note that image sources required this way include size (width, height) info for the Image. If you need to scale the image dynamically (i.e. via flex), you may need to manually set { width: undefined, height: undefined } on the style attribute.

Static Non-Image Resources

The require syntax described above can be used to statically include audio, video or document files in your project as well. Most common file types are supported including .mp3, .wav, .mp4, .mov, .html and .pdf. See bundler defaults for the full list.

You can add support for other types by adding an assetExts resolver option in your Metro configuration.

A caveat is that videos must use absolute positioning instead of flexGrow, since size info is not currently passed for non-image assets. This limitation doesn't occur for videos that are linked directly into Xcode or the Assets folder for Android.

Images From Hybrid App's Resources

If you are building a hybrid app (some UIs in React Native, some UIs in platform code) you can still use images that are already bundled into the app.

For images included via Xcode asset catalogs or in the Android drawable folder, use the image name without the extension:

<Image
source={{ uri: 'app_icon' }}
style={{ width: 40, height: 40 }}
/>

For images in the Android assets folder, use the asset:/ scheme:

<Image
source={{ uri: 'asset:/app_icon.png' }}
style={{ width: 40, height: 40 }}
/>

These approaches provide no safety checks. It's up to you to guarantee that those images are available in the application. Also you have to specify image dimensions manually.

Network Images

Many of the images you will display in your app will not be available at compile time, or you will want to load some dynamically to keep the binary size down. Unlike with static resources, you will need to manually specify the dimensions of your image. It's highly recommended that you use https as well in order to satisfy App Transport Security requirements on iOS.

// GOOD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}}
style={{width: 400, height: 400}} />
// 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.

  • default: Use the native platforms default strategy.
  • reload: The data for the URL will be loaded from the originating source. No existing cache data should be used to satisfy a URL load request.
  • force-cache: The existing cached data will be used to satisfy the request, regardless of its age or expiration date. If there is no existing data in the cache corresponding the request, the data is loaded from the originating source.
  • only-if-cached: The existing cache data will be used to satisfy a request, regardless of its age or expiration date. If there is no existing data in the cache corresponding to a URL load request, no attempt is made to load the data from the originating source, and the load is considered to have failed.
<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:

  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomLeftRadius
  • borderBottomRightRadius

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/index.html b/docs/next/improvingux/index.html index d733f218f4f..e54f271ee1e 100644 --- a/docs/next/improvingux/index.html +++ b/docs/next/improvingux/index.html @@ -16,7 +16,7 @@ Improving User Experience · React Native - + @@ -30,7 +30,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/index.html b/docs/next/inputaccessoryview/index.html index 5849b9b1ce1..a254af56745 100644 --- a/docs/next/inputaccessoryview/index.html +++ b/docs/next/inputaccessoryview/index.html @@ -16,7 +16,7 @@ InputAccessoryView · React Native - + @@ -30,7 +30,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/index.html b/docs/next/integration-with-android-fragment/index.html index e58ff57087e..57b27d9c854 100644 --- a/docs/next/integration-with-android-fragment/index.html +++ b/docs/next/integration-with-android-fragment/index.html @@ -16,7 +16,7 @@ Integration with an Android Fragment · React Native - + @@ -39,7 +39,7 @@
}
});
}

In the code above Fragment reactNativeFragment = new ReactFragment.Builder() creates the ReactFragment and getSupportFragmentManager().beginTransaction().add() adds the Fragment to the Frame Layout.

If you are using a starter kit for React Native, replace the "HelloWorld" string with the one in your index.js or index.android.js file (it’s the first argument to the AppRegistry.registerComponent() method).

Add the getLaunchOptions method which will allow you to pass props through to your component. This is optional and you can remove setLaunchOptions if you don't need to pass any props.

private Bundle getLaunchOptions(String message) {
Bundle initialProperties = new Bundle();
initialProperties.putString("message", message);
return initialProperties;
}

Add all missing imports in your Activity class. Be careful to use your package’s BuildConfig and not the one from the facebook package! Alternatively these are the required imports to include manually:

import android.app.Application;
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/index.html b/docs/next/integration-with-existing-apps/index.html index 406290dbbc4..f6a9d107c18 100644 --- a/docs/next/integration-with-existing-apps/index.html +++ b/docs/next/integration-with-existing-apps/index.html @@ -16,7 +16,7 @@ Integration with Existing Apps · React Native - + @@ -45,7 +45,7 @@
@Override
protected void onDestroy() {
super.onDestroy();
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/index.html b/docs/next/interactionmanager/index.html index b9ce9f5c3d0..407c2600ba3 100644 --- a/docs/next/interactionmanager/index.html +++ b/docs/next/interactionmanager/index.html @@ -16,7 +16,7 @@ InteractionManager · React Native - + @@ -30,7 +30,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).

Properties

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 2a042d5807f..5a2eabc6263 100644 --- a/docs/next/intro-react-native-components/index.html +++ b/docs/next/intro-react-native-components/index.html @@ -16,7 +16,7 @@ Core Components and Native Components · React Native - + @@ -30,7 +30,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/index.html b/docs/next/intro-react/index.html index 2ec87740cc5..edd8e415a25 100644 --- a/docs/next/intro-react/index.html +++ b/docs/next/intro-react/index.html @@ -16,7 +16,7 @@ React Fundamentals · React Native - + @@ -31,7 +31,7 @@
Version: Next

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:

const 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:

const 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:

const Cat = () => {
return <Text>Hello, I am your cat!</Text>;
};
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/index.html b/docs/next/javascript-environment/index.html index b5b38c9577a..33a95def919 100644 --- a/docs/next/javascript-environment/index.html +++ b/docs/next/javascript-environment/index.html @@ -16,7 +16,7 @@ JavaScript Environment · React Native - + @@ -30,7 +30,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/index.html b/docs/next/keyboard/index.html index 116ca202297..aa60dd23694 100644 --- a/docs/next/keyboard/index.html +++ b/docs/next/keyboard/index.html @@ -16,7 +16,7 @@ Keyboard · React Native - + @@ -30,7 +30,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:

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/next/keyboardavoidingview/index.html b/docs/next/keyboardavoidingview/index.html index c245ff117f5..e138e15b058 100644 --- a/docs/next/keyboardavoidingview/index.html +++ b/docs/next/keyboardavoidingview/index.html @@ -16,7 +16,7 @@ KeyboardAvoidingView · React Native - + @@ -30,7 +30,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/index.html b/docs/next/layout-props/index.html index ff9d2d24164..fb361750e05 100644 --- a/docs/next/layout-props/index.html +++ b/docs/next/layout-props/index.html @@ -16,7 +16,7 @@ Layout Props · React Native - + @@ -30,7 +30,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.

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/index.html b/docs/next/layoutanimation/index.html index 6517d10c3ce..ec8fbc50f7b 100644 --- a/docs/next/layoutanimation/index.html +++ b/docs/next/layoutanimation/index.html @@ -16,7 +16,7 @@ LayoutAnimation · React Native - + @@ -30,7 +30,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 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/next/layoutevent/index.html b/docs/next/layoutevent/index.html index e5af1ae3cd5..737ae0683a3 100644 --- a/docs/next/layoutevent/index.html +++ b/docs/next/layoutevent/index.html @@ -16,7 +16,7 @@ LayoutEvent Object Type · React Native - + @@ -30,7 +30,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/index.html b/docs/next/libraries/index.html index d6d16c73299..8312918a61e 100644 --- a/docs/next/libraries/index.html +++ b/docs/next/libraries/index.html @@ -16,7 +16,7 @@ Using Libraries · React Native - + @@ -30,7 +30,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 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/next/linking-libraries-ios/index.html b/docs/next/linking-libraries-ios/index.html index 163e37d2653..94540619485 100644 --- a/docs/next/linking-libraries-ios/index.html +++ b/docs/next/linking-libraries-ios/index.html @@ -16,7 +16,7 @@ Linking Libraries · React Native - + @@ -30,7 +30,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/index.html b/docs/next/linking/index.html index 29f0959975c..1f1e4a6927f 100644 --- a/docs/next/linking/index.html +++ b/docs/next/linking/index.html @@ -16,7 +16,7 @@ Linking · React Native - + @@ -30,7 +30,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

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

getInitialURL may return null while debugging is enabled. Disable the debugger to ensure it gets passed.

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/next/modal/index.html b/docs/next/modal/index.html index 18ac0a43abd..782760202b9 100644 --- a/docs/next/modal/index.html +++ b/docs/next/modal/index.html @@ -16,7 +16,7 @@ Modal · React Native - + @@ -30,7 +30,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.

  • 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/next/more-resources/index.html b/docs/next/more-resources/index.html index e3bc8b40012..4180040d0f8 100644 --- a/docs/next/more-resources/index.html +++ b/docs/next/more-resources/index.html @@ -16,7 +16,7 @@ More Resources · React Native - + @@ -30,7 +30,7 @@
Version: Next

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 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/index.html b/docs/next/native-components-android/index.html index 36f4482940d..9ef6cff4c4a 100644 --- a/docs/next/native-components-android/index.html +++ b/docs/next/native-components-android/index.html @@ -16,7 +16,7 @@ Native UI Components · React Native - + @@ -40,7 +40,7 @@
class MyCustomView extends React.Component {
constructor(props) {
super(props);
this._onChange = this._onChange.bind(this);
}
_onChange(event: Event) {
if (!this.props.onChangeMessage) {
return;
}
this.props.onChangeMessage(event.nativeEvent.message);
}
render() {
return <RCTMyCustomView {...this.props} onChange={this._onChange} />;
}
}
MyCustomView.propTypes = {
/**
* Callback that is called continuously when the user is dragging the map.
*/
onChangeMessage: PropTypes.func,
...
};
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
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 2fe00580a36..408f7b43c55 100644 --- a/docs/next/native-components-ios/index.html +++ b/docs/next/native-components-ios/index.html @@ -16,7 +16,7 @@ Native UI Components · React Native - + @@ -93,7 +93,7 @@
- (NSDictionary *)constantsToExport
{
UIDatePicker *dp = [[UIDatePicker alloc] init];
[dp layoutIfNeeded];
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/index.html b/docs/next/native-modules-android/index.html index 6df7180d047..d7ff3e3cec8 100644 --- a/docs/next/native-modules-android/index.html +++ b/docs/next/native-modules-android/index.html @@ -16,7 +16,7 @@ Native Modules · React Native - + @@ -81,7 +81,7 @@
@Override
public void onHostPause() {
// Activity `onPause`
}
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}
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 e7754fe4c52..3e377860e5e 100644 --- a/docs/next/native-modules-ios/index.html +++ b/docs/next/native-modules-ios/index.html @@ -16,7 +16,7 @@ Native Modules · React Native - + @@ -68,7 +68,7 @@
RCT_EXTERN_METHOD(addEvent:(NSString *)name location:(NSString *)location date:(nonnull NSNumber *)date)
@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/next/native-modules-setup/index.html b/docs/next/native-modules-setup/index.html index c72ac1545f7..58df9c9a331 100644 --- a/docs/next/native-modules-setup/index.html +++ b/docs/next/native-modules-setup/index.html @@ -16,7 +16,7 @@ Native Modules Setup · React Native - + @@ -30,7 +30,7 @@
Version: Next

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 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/next/navigation/index.html b/docs/next/navigation/index.html index 74864b21b9a..318cb9e23d4 100644 --- a/docs/next/navigation/index.html +++ b/docs/next/navigation/index.html @@ -16,7 +16,7 @@ Navigating Between Screens · React Native - + @@ -34,7 +34,7 @@
const Stack = createStackNavigator();
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 = () => {
return <Text>This is Jane'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/index.html b/docs/next/network/index.html index 644dcf4e741..b24309546e4 100644 --- a/docs/next/network/index.html +++ b/docs/next/network/index.html @@ -16,7 +16,7 @@ Networking · React Native - + @@ -36,7 +36,7 @@
ws.onerror = (e) => {
// an error occurred
console.log(e.message);
};
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

  • redirect:manual
  • credentials:omit
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 91a036f6d0f..a76885eab15 100644 --- a/docs/next/optimizing-flatlist-configuration/index.html +++ b/docs/next/optimizing-flatlist-configuration/index.html @@ -16,7 +16,7 @@ Optimizing Flatlist Configuration · React Native - + @@ -33,7 +33,7 @@
<FlatList
data={items}
renderItem={renderItem}
/>
// ...
}
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 b75e6554a3a..9955a25280b 100644 --- a/docs/next/out-of-tree-platforms/index.html +++ b/docs/next/out-of-tree-platforms/index.html @@ -16,7 +16,7 @@ Out-of-Tree Platforms · React Native - + @@ -30,7 +30,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/index.html b/docs/next/panresponder/index.html index 6e6de40e91c..a21f405f950 100644 --- a/docs/next/panresponder/index.html +++ b/docs/next/panresponder/index.html @@ -16,7 +16,7 @@ PanResponder · React Native - + @@ -32,7 +32,7 @@
onPanResponderGrant: (evt, gestureState) => {
// The gesture has started. Show visual feedback so the user knows
// what is happening!
// gestureState.d{x,y} will be set to zero now
},
onPanResponderMove: (evt, gestureState) => {
// The most recent move distance is gestureState.move{X,Y}
// The accumulated gesture distance since becoming responder is
// gestureState.d{x,y}
},
onPanResponderTerminationRequest: (evt, gestureState) =>
true,
onPanResponderRelease: (evt, gestureState) => {
// The user has released all touches while this view is the
// responder. This typically means a gesture has succeeded
},
onPanResponderTerminate: (evt, gestureState) => {
// Another component has become the responder, so this gesture
// should be cancelled
},
onShouldBlockNativeResponder: (evt, gestureState) => {
// Returns whether this component should block native components from becoming the JS
// responder. Returns true by default. Is currently only supported on android.
return true;
}
})
).current;
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:

  • onMoveShouldSetPanResponder: (e, gestureState) => {...}
  • onMoveShouldSetPanResponderCapture: (e, gestureState) => {...}
  • onStartShouldSetPanResponder: (e, gestureState) => {...}
  • onStartShouldSetPanResponderCapture: (e, gestureState) => {...}
  • onPanResponderReject: (e, gestureState) => {...}
  • onPanResponderGrant: (e, gestureState) => {...}
  • onPanResponderStart: (e, gestureState) => {...}
  • onPanResponderEnd: (e, gestureState) => {...}
  • onPanResponderRelease: (e, gestureState) => {...}
  • onPanResponderMove: (e, gestureState) => {...}
  • onPanResponderTerminate: (e, gestureState) => {...}
  • onPanResponderTerminationRequest: (e, gestureState) => {...}
  • onShouldBlockNativeResponder: (e, gestureState) => {...}

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/index.html b/docs/next/performance/index.html index b90a722279b..8ec8be033af 100644 --- a/docs/next/performance/index.html +++ b/docs/next/performance/index.html @@ -16,7 +16,7 @@ Performance Overview · React Native - + @@ -30,7 +30,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

  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/next/permissionsandroid/index.html b/docs/next/permissionsandroid/index.html index f3d1cc4a46c..ebc057289bf 100644 --- a/docs/next/permissionsandroid/index.html +++ b/docs/next/permissionsandroid/index.html @@ -16,7 +16,7 @@ PermissionsAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/next/picker-item/index.html index bd4b03886b7..6f68b4ea445 100644 --- a/docs/next/picker-item/index.html +++ b/docs/next/picker-item/index.html @@ -16,7 +16,7 @@ Picker.Item · React Native - + @@ -30,7 +30,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/index.html b/docs/next/picker-style-props/index.html index fd4f9ddc769..de0d7eff376 100644 --- a/docs/next/picker-style-props/index.html +++ b/docs/next/picker-style-props/index.html @@ -16,7 +16,7 @@ Picker Style Props · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/next/picker/index.html b/docs/next/picker/index.html index 1699d5a5ebe..0dbc19911bc 100644 --- a/docs/next/picker/index.html +++ b/docs/next/picker/index.html @@ -16,7 +16,7 @@ 🚧 Picker · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 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/next/pickerios/index.html b/docs/next/pickerios/index.html index fb11fe516ee..11ff1bbd108 100644 --- a/docs/next/pickerios/index.html +++ b/docs/next/pickerios/index.html @@ -16,7 +16,7 @@ 🚧 PickerIOS · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/next/pixelratio/index.html b/docs/next/pixelratio/index.html index dd853af36d1..6b6ce815db9 100644 --- a/docs/next/pixelratio/index.html +++ b/docs/next/pixelratio/index.html @@ -16,7 +16,7 @@ PixelRatio · React Native - + @@ -30,7 +30,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 > 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/next/platform-specific-code/index.html b/docs/next/platform-specific-code/index.html index 04faa806e0f..d2a9ae9d963 100644 --- a/docs/next/platform-specific-code/index.html +++ b/docs/next/platform-specific-code/index.html @@ -16,7 +16,7 @@ Platform Specific Code · React Native - + @@ -36,7 +36,7 @@
if (Platform.Version === 25) {
console.log('Running on Nougat!');
}

Detecting the iOS version

On iOS, the Version is a result of -[UIDevice systemVersion], which is a string with the current version of the operating system. An example of the system version is "10.3". For example, to detect the major version number on iOS:

import { Platform } from 'react-native';
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/platformcolor/index.html b/docs/next/platformcolor/index.html index 1e6943e4a46..1f49e759961 100644 --- a/docs/next/platformcolor/index.html +++ b/docs/next/platformcolor/index.html @@ -16,7 +16,7 @@ PlatformColor · React Native - + @@ -32,7 +32,7 @@
export default (App = () => (
<View>
<Text style={styles.labelCell}>
I am a special label color!
</Text>
</View>
));
const styles = StyleSheet.create({
labelCell: {
flex: 1,
alignItems: 'stretch',
...Platform.select({
ios: { color: PlatformColor('label') },
android: {
color: PlatformColor('?attr/colorControlNormal')
},
default: { color: 'black' }
})
}
});

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/index.html b/docs/next/pressable/index.html index 9759409882a..4ef183faded 100644 --- a/docs/next/pressable/index.html +++ b/docs/next/pressable/index.html @@ -16,7 +16,7 @@ Pressable · React Native - + @@ -30,7 +30,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

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/next/pressevent/index.html b/docs/next/pressevent/index.html index c5d572e1f19..84cf218e6e4 100644 --- a/docs/next/pressevent/index.html +++ b/docs/next/pressevent/index.html @@ -16,7 +16,7 @@ PressEvent Object Type · React Native - + @@ -30,7 +30,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/index.html b/docs/next/profile-hermes/index.html index 3b14c1fc8dc..6e1d280b6f6 100644 --- a/docs/next/profile-hermes/index.html +++ b/docs/next/profile-hermes/index.html @@ -16,7 +16,7 @@ Profiling with Hermes · React Native - + @@ -30,7 +30,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/index.html b/docs/next/profiling/index.html index ff0afdc020f..296a3a3f1d8 100644 --- a/docs/next/profiling/index.html +++ b/docs/next/profiling/index.html @@ -16,7 +16,7 @@ Profiling · React Native - + @@ -30,7 +30,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/index.html b/docs/next/progressbarandroid/index.html index 795424e65bd..f49c8a5772b 100644 --- a/docs/next/progressbarandroid/index.html +++ b/docs/next/progressbarandroid/index.html @@ -16,7 +16,7 @@ 🚧 ProgressBarAndroid · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 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/next/progressviewios/index.html b/docs/next/progressviewios/index.html index ed32839a8e6..8d24c324578 100644 --- a/docs/next/progressviewios/index.html +++ b/docs/next/progressviewios/index.html @@ -16,7 +16,7 @@ 🚧 ProgressViewIOS · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 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/next/props/index.html b/docs/next/props/index.html index f37e4e79697..93bfcb74578 100644 --- a/docs/next/props/index.html +++ b/docs/next/props/index.html @@ -16,7 +16,7 @@ Props · React Native - + @@ -30,7 +30,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/index.html b/docs/next/publishing-to-app-store/index.html index c74d5cb4ce7..f89ced2ef42 100644 --- a/docs/next/publishing-to-app-store/index.html +++ b/docs/next/publishing-to-app-store/index.html @@ -16,7 +16,7 @@ Publishing to Apple App Store · React Native - + @@ -30,7 +30,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/index.html b/docs/next/pushnotificationios/index.html index 71579a2e92c..54ab7c7f40d 100644 --- a/docs/next/pushnotificationios/index.html +++ b/docs/next/pushnotificationios/index.html @@ -16,7 +16,7 @@ 🚧 PushNotificationIOS · React Native - + @@ -32,7 +32,7 @@
return YES;
}
//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:

  • alertBody : The message displayed in the notification alert.
  • alertAction : The "action" displayed beneath an actionable notification. Defaults to "view". Note that Apple no longer shows this in iOS 10 +
  • alertTitle : The text displayed as the title of the notification alert.
  • soundName : The sound played when the notification is fired (optional).
  • isSilent : If true, the notification will appear without sound (optional).
  • category : The category of this notification, required for actionable notifications (optional).
  • userInfo : An object containing additional notification data (optional).
  • applicationIconBadgeNumber The number to display as the app's icon badge. The default value of this property is 0, which means that no badge is displayed (optional).

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

  • fireDate : The date and time when the system should deliver the notification.
  • alertTitle : The text displayed as the title of the notification alert.
  • alertBody : The message displayed in the notification alert.
  • alertAction : The "action" displayed beneath an actionable notification. Defaults to "view". Note that Apple no longer shows this in iOS 10 +
  • soundName : The sound played when the notification is fired (optional).
  • isSilent : If true, the notification will appear without sound (optional).
  • category : The category of this notification, required for actionable notifications (optional).
  • userInfo : An object containing additional notification data (optional).
  • applicationIconBadgeNumber The number to display as the app's icon badge. Setting the number to 0 removes the icon badge (optional).
  • repeatInterval : The interval to repeat as a string. Possible values: minute, hour, day, week, month, year (optional).

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:

  • identifier : The identifier of this notification.
  • title : The title of this notification.
  • body : The body of this notification.
  • category : The category of this notification (optional).
  • userInfo : An object containing additional notification data (optional).
  • thread-id : The thread identifier of this notification, if has one.

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:

  • notification : Fired when a remote notification is received. The handler will be invoked with an instance of PushNotificationIOS.
  • localNotification : Fired when a local notification is received. The handler will be invoked with an instance of PushNotificationIOS.
  • register: Fired when the user registers for remote notifications. The handler will be invoked with a hex string representing the deviceToken.
  • registrationError: Fired when the user fails to register for remote notifications. Typically occurs when APNS is having issues, or the device is a simulator. The handler will be invoked with {message: string, code: number, details: any}.

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:

  • alert
  • badge
  • sound

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:

  • alert :boolean
  • badge :boolean
  • sound :boolean

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/index.html b/docs/next/ram-bundles-inline-requires/index.html index a62e933e196..5bd056d9fed 100644 --- a/docs/next/ram-bundles-inline-requires/index.html +++ b/docs/next/ram-bundles-inline-requires/index.html @@ -16,7 +16,7 @@ RAM Bundles and Inline Requires · React Native - + @@ -42,7 +42,7 @@
const config = {
transformer: {
getTransformOptions: () => {
const moduleMap = {};
modulePaths.forEach((path) => {
if (fs.existsSync(path)) {
moduleMap[resolve(path)] = true;
}
});
return {
preloadedModules: moduleMap,
transform: { inlineRequires: { blacklist: moduleMap } }
};
}
},
projectRoot: ROOT_FOLDER
};
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/next/react-node/index.html b/docs/next/react-node/index.html index 6adb46b4454..316aaa8df05 100644 --- a/docs/next/react-node/index.html +++ b/docs/next/react-node/index.html @@ -16,7 +16,7 @@ React Node Object Type · React Native - + @@ -30,7 +30,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/index.html b/docs/next/rect/index.html index b4134f6a3e5..157846ac45c 100644 --- a/docs/next/rect/index.html +++ b/docs/next/rect/index.html @@ -16,7 +16,7 @@ Rect Object Type · React Native - + @@ -30,7 +30,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/index.html b/docs/next/refreshcontrol/index.html index e2cd32ae162..3e8f836cba1 100644 --- a/docs/next/refreshcontrol/index.html +++ b/docs/next/refreshcontrol/index.html @@ -16,7 +16,7 @@ RefreshControl · React Native - + @@ -30,7 +30,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 acctual 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/removing-default-permissions/index.html b/docs/next/removing-default-permissions/index.html index bfccd9945bb..61660d13cb8 100644 --- a/docs/next/removing-default-permissions/index.html +++ b/docs/next/removing-default-permissions/index.html @@ -16,7 +16,7 @@ Removing Default Permissions · React Native - + @@ -30,7 +30,7 @@
Version: Next

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/next/running-on-device/index.html b/docs/next/running-on-device/index.html index 5aef41dc242..2ccad1dfca1 100644 --- a/docs/next/running-on-device/index.html +++ b/docs/next/running-on-device/index.html @@ -16,7 +16,7 @@ Running On Device · React Native - + @@ -30,7 +30,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/index.html b/docs/next/running-on-simulator-ios/index.html index 74b1a37ed2d..1e0fd48f0af 100644 --- a/docs/next/running-on-simulator-ios/index.html +++ b/docs/next/running-on-simulator-ios/index.html @@ -16,7 +16,7 @@ Running On Simulator · React Native - + @@ -30,7 +30,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/index.html b/docs/next/safeareaview/index.html index 8ef8dd8612e..b003dda2799 100644 --- a/docs/next/safeareaview/index.html +++ b/docs/next/safeareaview/index.html @@ -16,7 +16,7 @@ SafeAreaView · React Native - + @@ -30,7 +30,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/index.html b/docs/next/scrollview/index.html index c1107c248d2..da4a9c2ce86 100644 --- a/docs/next/scrollview/index.html +++ b/docs/next/scrollview/index.html @@ -16,7 +16,7 @@ ScrollView · React Native - + @@ -30,7 +30,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.

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 pagination when the page is less than the width of the horizontal ScrollView or the height of the vertical 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/next/sectionlist/index.html b/docs/next/sectionlist/index.html index f4daacc0f05..3c97b5ab7ef 100644 --- a/docs/next/sectionlist/index.html +++ b/docs/next/sectionlist/index.html @@ -16,7 +16,7 @@ SectionList · React Native - + @@ -30,7 +30,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, function

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 Class, a render function, or a rendered element.

Type
component, element, function

ListFooterComponent

Rendered at the very end of the list. Can be a React Component Class, a render function, or a rendered element.

Type
component, element, function

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component Class, a render function, or a rendered element.

Type
component, element, function

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, function

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, function, 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/index.html b/docs/next/security/index.html index 3a5c8a3edb8..448b30afaf0 100644 --- a/docs/next/security/index.html +++ b/docs/next/security/index.html @@ -16,7 +16,7 @@ Security · React Native - + @@ -30,7 +30,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 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 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/index.html b/docs/next/segmentedcontrolios/index.html index 2482dfa7786..a17f744c0fe 100644 --- a/docs/next/segmentedcontrolios/index.html +++ b/docs/next/segmentedcontrolios/index.html @@ -16,7 +16,7 @@ 🚧 SegmentedControlIOS · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 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

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/index.html b/docs/next/settings/index.html index 7e2ac84a217..785a70d1808 100644 --- a/docs/next/settings/index.html +++ b/docs/next/settings/index.html @@ -16,7 +16,7 @@ Settings · React Native - + @@ -30,7 +30,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/index.html b/docs/next/shadow-props/index.html index 634a3a1a938..2d725983be4 100644 --- a/docs/next/shadow-props/index.html +++ b/docs/next/shadow-props/index.html @@ -16,7 +16,7 @@ Shadow Props · React Native - + @@ -30,7 +30,7 @@
Version: Next

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/next/share/index.html b/docs/next/share/index.html index 30a647881d3..24f68ffc670 100644 --- a/docs/next/share/index.html +++ b/docs/next/share/index.html @@ -16,7 +16,7 @@ Share · React Native - + @@ -30,7 +30,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.

Content

  • message - a message to share

iOS

  • url - a 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/next/signed-apk-android/index.html b/docs/next/signed-apk-android/index.html index d2faeddac8f..00b85487520 100644 --- a/docs/next/signed-apk-android/index.html +++ b/docs/next/signed-apk-android/index.html @@ -16,7 +16,7 @@ Publishing to Google Play Store · React Native - + @@ -30,7 +30,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.

Edit this page
Last updated on
- + diff --git a/docs/next/slider/index.html b/docs/next/slider/index.html index 3ec33e35ce6..6a91c954fbc 100644 --- a/docs/next/slider/index.html +++ b/docs/next/slider/index.html @@ -16,7 +16,7 @@ 🚧 Slider · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 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/next/state/index.html b/docs/next/state/index.html index a85c9abcf55..92dd9f3c217 100644 --- a/docs/next/state/index.html +++ b/docs/next/state/index.html @@ -16,7 +16,7 @@ State · React Native - + @@ -30,7 +30,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/index.html b/docs/next/statusbar/index.html index f2a0c02a7e3..e140fe25049 100644 --- a/docs/next/statusbar/index.html +++ b/docs/next/statusbar/index.html @@ -16,7 +16,7 @@ StatusBar · React Native - + @@ -30,7 +30,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/index.html b/docs/next/statusbarios/index.html index f97b76c02f1..07f4a130c01 100644 --- a/docs/next/statusbarios/index.html +++ b/docs/next/statusbarios/index.html @@ -16,7 +16,7 @@ 🚧 StatusBarIOS · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 StatusBarIOS

Deprecated. Use StatusBar for mutating the status bar.

Edit this page
Last updated on
- + diff --git a/docs/next/style/index.html b/docs/next/style/index.html index 68870c2c878..448b9e15439 100644 --- a/docs/next/style/index.html +++ b/docs/next/style/index.html @@ -16,7 +16,7 @@ Style · React Native - + @@ -30,7 +30,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/index.html b/docs/next/stylesheet/index.html index 8443a1dc700..edd13987de4 100644 --- a/docs/next/stylesheet/index.html +++ b/docs/next/stylesheet/index.html @@ -16,7 +16,7 @@ StyleSheet · React Native - + @@ -30,7 +30,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/index.html b/docs/next/switch/index.html index 638992c6d33..5ff74dcef84 100644 --- a/docs/next/switch/index.html +++ b/docs/next/switch/index.html @@ -16,7 +16,7 @@ Switch · React Native - + @@ -30,7 +30,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/index.html b/docs/next/symbolication/index.html index 949e8e7af9c..79c80fd61d0 100644 --- a/docs/next/symbolication/index.html +++ b/docs/next/symbolication/index.html @@ -16,7 +16,7 @@ Symbolicating a stack trace · React Native - + @@ -30,7 +30,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/index.html b/docs/next/systrace/index.html index 30c0412ab5b..ca043599090 100644 --- a/docs/next/systrace/index.html +++ b/docs/next/systrace/index.html @@ -16,7 +16,7 @@ Systrace · React Native - + @@ -30,7 +30,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/index.html b/docs/next/testing-overview/index.html index c4e80049c99..8223098240f 100644 --- a/docs/next/testing-overview/index.html +++ b/docs/next/testing-overview/index.html @@ -16,7 +16,7 @@ Testing · React Native - + @@ -34,7 +34,7 @@
fireEvent.changeText(
getByPlaceholder('Enter grocery item'),
'banana'
);
fireEvent.press(getByText('Add the item to list'));
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:

  • For you as a developer or reviewer, it can be hard to tell whether a change in snapshot is intended or whether it's evidence of a bug. Especially large snapshots can quickly become hard to understand and their added value becomes low.
  • When snapshot is created, at that point it is considered to be correct-even in the case when the rendered output is actually wrong.
  • When a snapshot fails, it's tempting to update it using the --updateSnapshot jest option without taking proper care to investigate whether the change is expected. Certain developer discipline is thus needed.

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:

  • writing them is more time consuming compared to the other types of tests
  • they are slower to run
  • they are more prone to flakiness (a "flaky" test is a test which randomly passes and fails without any change to code)

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/index.html b/docs/next/text-style-props/index.html index c24efac7a1d..2d0f919296a 100644 --- a/docs/next/text-style-props/index.html +++ b/docs/next/text-style-props/index.html @@ -16,7 +16,7 @@ Text Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/next/text/index.html index 6c3cacc775f..4e3d6db4aa6 100644 --- a/docs/next/text/index.html +++ b/docs/next/text/index.html @@ -16,7 +16,7 @@ Text · React Native - + @@ -34,7 +34,7 @@
// otherwise, the text will flow in its own block
// |First part |
// |and |
// |second part|

Limited Style Inheritance

On the web, the usual way to set a font family and size for the entire document is to take advantage of inherited CSS properties like so:

html {
font-family: 'lucida grande', tahoma, verdana, arial, sans-serif;
font-size: 11px;
color: #141823;
}

All elements in the document will inherit this font unless they or one of their parents specifies a new rule.

In React Native, we are more strict about it: you must wrap all the text nodes inside of a <Text> component. You cannot have a text node directly under a <View>.

// BAD: will raise exception, can't have a text node as child of a <View>
<View>
Some text
</View>
// 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:

  • (Developer) React components are designed with strong isolation in mind: You should be able to drop a component anywhere in your application, trusting that as long as the props are the same, it will look and behave the same way. Text properties that could inherit from outside of the props would break this isolation.

  • (Implementor) The implementation of React Native is also simplified. We do not need to have a fontFamily field on every single element, and we do not need to potentially traverse the tree up to the root every time we display a text node. The style inheritance is only encoded inside of the native Text component and doesn't leak to other components or the system itself.

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
iOS

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:

  • head - The line is displayed so that the end fits in the container and the missing text at the beginning of the line is indicated by an ellipsis glyph. e.g., "...wxyz"
  • middle - The line is displayed so that the beginning and end fit in the container and the missing text in the middle is indicated by an ellipsis glyph. "ab...yz"
  • tail - The line is displayed so that the beginning fits in the container and the missing text at the end of the line is indicated by an ellipsis glyph. e.g., "abcd..."
  • clip - Lines are not drawn past the edge of the text container.
TypeDefault
enum('head', 'middle', 'tail', 'clip')tail

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

  • null/undefined: 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
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 Props, 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/index.html b/docs/next/textinput/index.html index b762b72995a..3475269cb24 100644 --- a/docs/next/textinput/index.html +++ b/docs/next/textinput/index.html @@ -16,7 +16,7 @@ TextInput · React Native - + @@ -30,7 +30,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=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

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 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.

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.

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.

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/index.html b/docs/next/timepickerandroid/index.html index 7516f194760..4c2f66f0a07 100644 --- a/docs/next/timepickerandroid/index.html +++ b/docs/next/timepickerandroid/index.html @@ -16,7 +16,7 @@ 🚧 TimePickerAndroid · React Native - + @@ -30,7 +30,7 @@
Version: Next

🚧 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/next/timers/index.html b/docs/next/timers/index.html index 8e49bc4e74a..14c63df3c54 100644 --- a/docs/next/timers/index.html +++ b/docs/next/timers/index.html @@ -16,7 +16,7 @@ Timers · React Native - + @@ -30,7 +30,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/index.html b/docs/next/toastandroid/index.html index 598862ef884..4df03599625 100644 --- a/docs/next/toastandroid/index.html +++ b/docs/next/toastandroid/index.html @@ -16,7 +16,7 @@ ToastAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/next/touchablehighlight/index.html index eed94ca6a04..23f2234db84 100644 --- a/docs/next/touchablehighlight/index.html +++ b/docs/next/touchablehighlight/index.html @@ -16,7 +16,7 @@ TouchableHighlight · React Native - + @@ -31,7 +31,7 @@
Version: Next

TouchableHighlight

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, 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.

function MyComponent(props) {
return (
<View {...props} style={{ flex: 1, backgroundColor: '#fff' }}>
<Text>My Component</Text>
</View>
);
}
<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/index.html b/docs/next/touchablenativefeedback/index.html index 6e669f39873..e25621d3e93 100644 --- a/docs/next/touchablenativefeedback/index.html +++ b/docs/next/touchablenativefeedback/index.html @@ -16,7 +16,7 @@ TouchableNativeFeedback · React Native - + @@ -30,7 +30,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/index.html b/docs/next/touchableopacity/index.html index 526d5bb2e79..7556d49e88c 100644 --- a/docs/next/touchableopacity/index.html +++ b/docs/next/touchableopacity/index.html @@ -16,7 +16,7 @@ TouchableOpacity · React Native - + @@ -30,7 +30,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

Methods

setOpacityTo()

setOpacityTo((value: number), (duration: number));

Animate the touchable to a new opacity.

Edit this page
Last updated on
- + diff --git a/docs/next/touchablewithoutfeedback/index.html b/docs/next/touchablewithoutfeedback/index.html index 05fe48a37ab..6ee5666187f 100644 --- a/docs/next/touchablewithoutfeedback/index.html +++ b/docs/next/touchablewithoutfeedback/index.html @@ -16,7 +16,7 @@ TouchableWithoutFeedback · React Native - + @@ -31,7 +31,7 @@
Version: Next

TouchableWithoutFeedback

If you're looking for a more extensive and future-proof way to handle touch-based input, check out the Pressable API.

Do not use unless you have a very good reason. All elements that respond to press should have a visual feedback when touched.

TouchableWithoutFeedback supports only one child. If you wish to have several child components, wrap them in a View. Importantly, TouchableWithoutFeedback works by cloning its child and applying responder props to it. It is therefore required that any intermediary components pass through those props to the underlying React Native component.

Usage Pattern

function MyComponent(props) {
return (
<View {...props} style={{ flex: 1, backgroundColor: '#fff' }}>
<Text>My Component</Text>
</View>
);
}
<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:

  • '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

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/index.html b/docs/next/transforms/index.html index 0fc054924f5..8172be3b48b 100644 --- a/docs/next/transforms/index.html +++ b/docs/next/transforms/index.html @@ -16,7 +16,7 @@ Transforms · React Native - + @@ -30,7 +30,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/index.html b/docs/next/troubleshooting/index.html index 9ffa1557b8a..81ac9bf437f 100644 --- a/docs/next/troubleshooting/index.html +++ b/docs/next/troubleshooting/index.html @@ -16,7 +16,7 @@ Troubleshooting · React Native - + @@ -30,7 +30,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/index.html b/docs/next/tutorial/index.html index b9628a9e015..26f2d272720 100644 --- a/docs/next/tutorial/index.html +++ b/docs/next/tutorial/index.html @@ -16,7 +16,7 @@ Learn the Basics · React Native - + @@ -42,7 +42,7 @@
return (
<View style={styles.container}>
<Text>You clicked {count} times</Text>
<Button
onPress={() => setCount(count + 1)}
title="Click me!"
/>
</View>
);
};
// 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/index.html b/docs/next/typescript/index.html index 44457138358..a74d0468bc9 100644 --- a/docs/next/typescript/index.html +++ b/docs/next/typescript/index.html @@ -16,7 +16,7 @@ Using TypeScript · React Native - + @@ -36,7 +36,7 @@
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'
}
});
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/index.html b/docs/next/upgrading/index.html index 1080f350d88..825c6ce3375 100644 --- a/docs/next/upgrading/index.html +++ b/docs/next/upgrading/index.html @@ -16,7 +16,7 @@ Upgrading to new versions · React Native - + @@ -30,7 +30,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/index.html b/docs/next/usecolorscheme/index.html index 50e5ea788e6..ef41ee587db 100644 --- a/docs/next/usecolorscheme/index.html +++ b/docs/next/usecolorscheme/index.html @@ -16,7 +16,7 @@ useColorScheme · React Native - + @@ -31,7 +31,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.
import { Text, useColorScheme } from 'react-native';
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/next/usewindowdimensions/index.html b/docs/next/usewindowdimensions/index.html index 1136edcb2d4..13b2a3ea651 100644 --- a/docs/next/usewindowdimensions/index.html +++ b/docs/next/usewindowdimensions/index.html @@ -16,7 +16,7 @@ useWindowDimensions · React Native - + @@ -30,7 +30,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

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/next/using-a-listview/index.html b/docs/next/using-a-listview/index.html index ce07310ce0a..15fec392b99 100644 --- a/docs/next/using-a-listview/index.html +++ b/docs/next/using-a-listview/index.html @@ -16,7 +16,7 @@ Using List Views · React Native - + @@ -30,7 +30,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/index.html b/docs/next/using-a-scrollview/index.html index 3e65d2efa9a..0a36170cf82 100644 --- a/docs/next/using-a-scrollview/index.html +++ b/docs/next/using-a-scrollview/index.html @@ -16,7 +16,7 @@ Using a ScrollView · React Native - + @@ -30,7 +30,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/index.html b/docs/next/vibration/index.html index 924205d96ec..b8f6d91bf67 100644 --- a/docs/next/vibration/index.html +++ b/docs/next/vibration/index.html @@ -16,7 +16,7 @@ Vibration · React Native - + @@ -30,7 +30,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

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/next/view-style-props/index.html b/docs/next/view-style-props/index.html index e59d49715b5..156668cfa5a 100644 --- a/docs/next/view-style-props/index.html +++ b/docs/next/view-style-props/index.html @@ -16,7 +16,7 @@ View Style Props · React Native - + @@ -30,7 +30,7 @@
Version: Next

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/next/view/index.html b/docs/next/view/index.html index aabdb9a652d..971c2e3742f 100644 --- a/docs/next/view/index.html +++ b/docs/next/view/index.html @@ -16,7 +16,7 @@ View · React Native - + @@ -30,7 +30,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 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/next/viewpagerandroid/index.html b/docs/next/viewpagerandroid/index.html index 0d7537752fb..54228b4b523 100644 --- a/docs/next/viewpagerandroid/index.html +++ b/docs/next/viewpagerandroid/index.html @@ -16,7 +16,7 @@ 🚧 ViewPagerAndroid · React Native - + @@ -32,7 +32,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.

  • '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

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:

  • position - index of first page from the left that is currently visible
  • offset - value from range [0, 1] describing stage between page transitions. Value x means that (1 - x) fraction of the page at "position" index is visible, and x fraction of the next page is visible.
TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

  • idle, meaning there is no interaction with the page scroller happening at the time
  • dragging, meaning there is currently an interaction with the page scroller
  • settling, meaning that there was an interaction with the page scroller, and the page scroller is now finishing its closing or opening animation
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:

  • position - index of page that has been selected
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.

  • position - index of page that will be selected
TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

  • position - index of page that will be selected
TypeRequired
NumberYes

Type Definitions

ViewPagerScrollState

Type
\$Enum

Constants:

ValueDescription
idle
dragging
settling
Edit this page
Last updated on
- + diff --git a/docs/next/viewtoken/index.html b/docs/next/viewtoken/index.html index 32a1cce2715..9ea9e675769 100644 --- a/docs/next/viewtoken/index.html +++ b/docs/next/viewtoken/index.html @@ -16,7 +16,7 @@ ViewToken Object Type · React Native - + @@ -30,7 +30,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/index.html b/docs/next/virtualizedlist/index.html index c2ad1851cfe..7be7499cf34 100644 --- a/docs/next/virtualizedlist/index.html +++ b/docs/next/virtualizedlist/index.html @@ -16,7 +16,7 @@ VirtualizedList · React Native - + @@ -33,7 +33,7 @@
- 'animated' (boolean). Optional default is true.

scrollToIndex()

scrollToIndex((params: object));

Valid params consist of:

  • 'animated' (boolean). Optional.
  • 'index' (number). Required.
  • 'viewOffset' (number). Optional.
  • 'viewPosition' (number). Optional.

scrollToItem()

scrollToItem((params: object));

Valid params consist of:

  • 'animated' (boolean). Optional.
  • 'item' (Item). Required.
  • 'viewPosition' (number). Optional.

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:

  • 'virtualizedList' (Object). This object consist of the following
    • getScrollMetrics' (Function). Returns an object with following properties: { contentLength: number, dOffset: number, dt: number, offset: number, timestamp: number, velocity: number, visibleLength: number }.
    • 'horizontal' (boolean) - Optional.
    • 'getOutermostParentListRef' (Function).
    • 'getNestedChildState' (Function) - Returns ChildListState .
    • 'registerAsNestedChild' (Function). This accept an object with following properties { cellKey: string, key: string, ref: VirtualizedList, parentDebugInfo: ListDebugInfo }. It returns a ChildListState
    • 'unregisterAsNestedChild' (Function). This takes an object with following properties, { key: string, state: ChildListState }
    • 'debugInfo' (ListDebugInfo).

hasMore()

hasMore () => boolean;
Edit this page
Last updated on
- + diff --git a/docs/optimizing-flatlist-configuration/index.html b/docs/optimizing-flatlist-configuration/index.html index ae7c50d8026..cd0a0c8ca73 100644 --- a/docs/optimizing-flatlist-configuration/index.html +++ b/docs/optimizing-flatlist-configuration/index.html @@ -16,7 +16,7 @@ Optimizing Flatlist Configuration · React Native - + @@ -33,7 +33,7 @@
<FlatList
data={items}
renderItem={renderItem}
/>
// ...
}
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 a84e67002dc..42a78b466a2 100644 --- a/docs/out-of-tree-platforms/index.html +++ b/docs/out-of-tree-platforms/index.html @@ -16,7 +16,7 @@ Out-of-Tree Platforms · React Native - + @@ -30,7 +30,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/index.html b/docs/panresponder/index.html index ae888c25310..d28f2d4ed5f 100644 --- a/docs/panresponder/index.html +++ b/docs/panresponder/index.html @@ -16,7 +16,7 @@ PanResponder · React Native - + @@ -32,7 +32,7 @@
onPanResponderGrant: (evt, gestureState) => {
// The gesture has started. Show visual feedback so the user knows
// what is happening!
// gestureState.d{x,y} will be set to zero now
},
onPanResponderMove: (evt, gestureState) => {
// The most recent move distance is gestureState.move{X,Y}
// The accumulated gesture distance since becoming responder is
// gestureState.d{x,y}
},
onPanResponderTerminationRequest: (evt, gestureState) =>
true,
onPanResponderRelease: (evt, gestureState) => {
// The user has released all touches while this view is the
// responder. This typically means a gesture has succeeded
},
onPanResponderTerminate: (evt, gestureState) => {
// Another component has become the responder, so this gesture
// should be cancelled
},
onShouldBlockNativeResponder: (evt, gestureState) => {
// Returns whether this component should block native components from becoming the JS
// responder. Returns true by default. Is currently only supported on android.
return true;
}
})
).current;
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:

  • onMoveShouldSetPanResponder: (e, gestureState) => {...}
  • onMoveShouldSetPanResponderCapture: (e, gestureState) => {...}
  • onStartShouldSetPanResponder: (e, gestureState) => {...}
  • onStartShouldSetPanResponderCapture: (e, gestureState) => {...}
  • onPanResponderReject: (e, gestureState) => {...}
  • onPanResponderGrant: (e, gestureState) => {...}
  • onPanResponderStart: (e, gestureState) => {...}
  • onPanResponderEnd: (e, gestureState) => {...}
  • onPanResponderRelease: (e, gestureState) => {...}
  • onPanResponderMove: (e, gestureState) => {...}
  • onPanResponderTerminate: (e, gestureState) => {...}
  • onPanResponderTerminationRequest: (e, gestureState) => {...}
  • onShouldBlockNativeResponder: (e, gestureState) => {...}

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/index.html b/docs/performance/index.html index ad8301d4bb3..357d6f5e7b0 100644 --- a/docs/performance/index.html +++ b/docs/performance/index.html @@ -16,7 +16,7 @@ Performance Overview · React Native - + @@ -30,7 +30,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

  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/permissionsandroid/index.html b/docs/permissionsandroid/index.html index 7c4baa3bf3b..e25070b1b2c 100644 --- a/docs/permissionsandroid/index.html +++ b/docs/permissionsandroid/index.html @@ -16,7 +16,7 @@ PermissionsAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/picker-item/index.html index 696f19f1928..10d32383a53 100644 --- a/docs/picker-item/index.html +++ b/docs/picker-item/index.html @@ -16,7 +16,7 @@ Picker.Item · React Native - + @@ -30,7 +30,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/index.html b/docs/picker-style-props/index.html index 69451e0dde3..1f200a924c8 100644 --- a/docs/picker-style-props/index.html +++ b/docs/picker-style-props/index.html @@ -16,7 +16,7 @@ Picker Style Props · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/picker/index.html b/docs/picker/index.html index 29f996660b2..a13802da8e3 100644 --- a/docs/picker/index.html +++ b/docs/picker/index.html @@ -16,7 +16,7 @@ 🚧 Picker · React Native - + @@ -30,7 +30,7 @@

🚧 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/pickerios/index.html b/docs/pickerios/index.html index 15173a2475b..398943a2700 100644 --- a/docs/pickerios/index.html +++ b/docs/pickerios/index.html @@ -16,7 +16,7 @@ 🚧 PickerIOS · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/pixelratio/index.html b/docs/pixelratio/index.html index 2d555552a4f..f8f70d89f12 100644 --- a/docs/pixelratio/index.html +++ b/docs/pixelratio/index.html @@ -16,7 +16,7 @@ PixelRatio · React Native - + @@ -30,7 +30,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/index.html b/docs/platform-specific-code/index.html index 37f7d82f03a..2dc6e97b687 100644 --- a/docs/platform-specific-code/index.html +++ b/docs/platform-specific-code/index.html @@ -16,7 +16,7 @@ Platform Specific Code · React Native - + @@ -36,7 +36,7 @@
if (Platform.Version === 25) {
console.log('Running on Nougat!');
}

Detecting the iOS version

On iOS, the Version is a result of -[UIDevice systemVersion], which is a string with the current version of the operating system. An example of the system version is "10.3". For example, to detect the major version number on iOS:

import { Platform } from 'react-native';
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/platformcolor/index.html b/docs/platformcolor/index.html index 2db060927a1..2bbf41c8742 100644 --- a/docs/platformcolor/index.html +++ b/docs/platformcolor/index.html @@ -16,7 +16,7 @@ PlatformColor · React Native - + @@ -32,7 +32,7 @@
export default (App = () => (
<View>
<Text style={styles.labelCell}>
I am a special label color!
</Text>
</View>
));
const styles = StyleSheet.create({
labelCell: {
flex: 1,
alignItems: 'stretch',
...Platform.select({
ios: { color: PlatformColor('label') },
android: {
color: PlatformColor('?attr/colorControlNormal')
},
default: { color: 'black' }
})
}
});

The string value provided to the PlatformColor function must match and agree with the same string as it exists on the native platform the app is being run on. This means to avoid runtime errors the function should be wrapped in a platform check, either through a Platform.OS === 'platform' or a Platform.Select().

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/index.html b/docs/pressable/index.html index 1cf6ff97835..a4647366fa8 100644 --- a/docs/pressable/index.html +++ b/docs/pressable/index.html @@ -16,7 +16,7 @@ Pressable · React Native - + @@ -30,7 +30,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/index.html b/docs/pressevent/index.html index 3a8816c6e5d..9224aa0fff1 100644 --- a/docs/pressevent/index.html +++ b/docs/pressevent/index.html @@ -16,7 +16,7 @@ PressEvent Object Type · React Native - + @@ -30,7 +30,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/index.html b/docs/profiling/index.html index 4fb7f8366cc..64054f87be6 100644 --- a/docs/profiling/index.html +++ b/docs/profiling/index.html @@ -16,7 +16,7 @@ Profiling · React Native - + @@ -30,7 +30,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/index.html b/docs/progressbarandroid/index.html index b7c37834cd9..f8d19697206 100644 --- a/docs/progressbarandroid/index.html +++ b/docs/progressbarandroid/index.html @@ -16,7 +16,7 @@ 🚧 ProgressBarAndroid · React Native - + @@ -30,7 +30,7 @@

🚧 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/progressviewios/index.html b/docs/progressviewios/index.html index dbe0a2d7c98..469479f27ca 100644 --- a/docs/progressviewios/index.html +++ b/docs/progressviewios/index.html @@ -16,7 +16,7 @@ 🚧 ProgressViewIOS · React Native - + @@ -30,7 +30,7 @@

🚧 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/props/index.html b/docs/props/index.html index f394ffd1d1e..93b664dcce2 100644 --- a/docs/props/index.html +++ b/docs/props/index.html @@ -16,7 +16,7 @@ Props · React Native - + @@ -30,7 +30,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 c676943b976..793b8aefa8e 100644 --- a/docs/publishing-forks/index.html +++ b/docs/publishing-forks/index.html @@ -16,7 +16,7 @@ Publish your own version of react native · React Native - + @@ -30,7 +30,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/index.html b/docs/publishing-to-app-store/index.html index 57b02e19e14..3fbbec56cf7 100644 --- a/docs/publishing-to-app-store/index.html +++ b/docs/publishing-to-app-store/index.html @@ -16,7 +16,7 @@ Publishing to Apple App Store · React Native - + @@ -30,7 +30,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/index.html b/docs/pushnotificationios/index.html index 64ce14d6268..8a79c0b4efd 100644 --- a/docs/pushnotificationios/index.html +++ b/docs/pushnotificationios/index.html @@ -16,7 +16,7 @@ 🚧 PushNotificationIOS · React Native - + @@ -32,7 +32,7 @@
return YES;
}
//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:

  • alertBody : The message displayed in the notification alert.
  • alertAction : The "action" displayed beneath an actionable notification. Defaults to "view". Note that Apple no longer shows this in iOS 10 +
  • alertTitle : The text displayed as the title of the notification alert.
  • soundName : The sound played when the notification is fired (optional).
  • isSilent : If true, the notification will appear without sound (optional).
  • category : The category of this notification, required for actionable notifications (optional).
  • userInfo : An object containing additional notification data (optional).
  • applicationIconBadgeNumber The number to display as the app's icon badge. The default value of this property is 0, which means that no badge is displayed (optional).

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

  • fireDate : The date and time when the system should deliver the notification.
  • alertTitle : The text displayed as the title of the notification alert.
  • alertBody : The message displayed in the notification alert.
  • alertAction : The "action" displayed beneath an actionable notification. Defaults to "view". Note that Apple no longer shows this in iOS 10 +
  • soundName : The sound played when the notification is fired (optional).
  • isSilent : If true, the notification will appear without sound (optional).
  • category : The category of this notification, required for actionable notifications (optional).
  • userInfo : An object containing additional notification data (optional).
  • applicationIconBadgeNumber The number to display as the app's icon badge. Setting the number to 0 removes the icon badge (optional).
  • repeatInterval : The interval to repeat as a string. Possible values: minute, hour, day, week, month, year (optional).

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:

  • identifier : The identifier of this notification.
  • title : The title of this notification.
  • body : The body of this notification.
  • category : The category of this notification (optional).
  • userInfo : An object containing additional notification data (optional).
  • thread-id : The thread identifier of this notification, if has one.

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:

  • notification : Fired when a remote notification is received. The handler will be invoked with an instance of PushNotificationIOS.
  • localNotification : Fired when a local notification is received. The handler will be invoked with an instance of PushNotificationIOS.
  • register: Fired when the user registers for remote notifications. The handler will be invoked with a hex string representing the deviceToken.
  • registrationError: Fired when the user fails to register for remote notifications. Typically occurs when APNS is having issues, or the device is a simulator. The handler will be invoked with {message: string, code: number, details: any}.

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:

  • alert
  • badge
  • sound

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:

  • alert :boolean
  • badge :boolean
  • sound :boolean

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/index.html b/docs/ram-bundles-inline-requires/index.html index 8f7a5b60636..b20c4b8a555 100644 --- a/docs/ram-bundles-inline-requires/index.html +++ b/docs/ram-bundles-inline-requires/index.html @@ -16,7 +16,7 @@ RAM Bundles and Inline Requires · React Native - + @@ -42,7 +42,7 @@
const config = {
transformer: {
getTransformOptions: () => {
const moduleMap = {};
modulePaths.forEach((path) => {
if (fs.existsSync(path)) {
moduleMap[resolve(path)] = true;
}
});
return {
preloadedModules: moduleMap,
transform: { inlineRequires: { blacklist: moduleMap } }
};
}
},
projectRoot: ROOT_FOLDER
};
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/index.html b/docs/react-node/index.html index 88de44c6f86..d46f1168fed 100644 --- a/docs/react-node/index.html +++ b/docs/react-node/index.html @@ -16,7 +16,7 @@ React Node Object Type · React Native - + @@ -30,7 +30,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/index.html b/docs/rect/index.html index 8d389f5e005..6b5385d8c61 100644 --- a/docs/rect/index.html +++ b/docs/rect/index.html @@ -16,7 +16,7 @@ Rect Object Type · React Native - + @@ -30,7 +30,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/index.html b/docs/refreshcontrol/index.html index e1b284e6478..6bcc4df2c92 100644 --- a/docs/refreshcontrol/index.html +++ b/docs/refreshcontrol/index.html @@ -16,7 +16,7 @@ RefreshControl · React Native - + @@ -30,7 +30,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/index.html b/docs/removing-default-permissions/index.html index 46cd07282f4..8862f724d9e 100644 --- a/docs/removing-default-permissions/index.html +++ b/docs/removing-default-permissions/index.html @@ -16,7 +16,7 @@ Removing Default Permissions · React Native - + @@ -30,7 +30,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/index.html b/docs/running-on-device/index.html index e8cd5f52dc4..6da9823ac51 100644 --- a/docs/running-on-device/index.html +++ b/docs/running-on-device/index.html @@ -16,7 +16,7 @@ Running On Device · React Native - + @@ -30,7 +30,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/index.html b/docs/running-on-simulator-ios/index.html index 88b54c1f787..8b45da4cd0e 100644 --- a/docs/running-on-simulator-ios/index.html +++ b/docs/running-on-simulator-ios/index.html @@ -16,7 +16,7 @@ Running On Simulator · React Native - + @@ -30,7 +30,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/index.html b/docs/safeareaview/index.html index 1ac93ae10f6..62536789b41 100644 --- a/docs/safeareaview/index.html +++ b/docs/safeareaview/index.html @@ -16,7 +16,7 @@ SafeAreaView · React Native - + @@ -30,7 +30,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/index.html b/docs/scrollview/index.html index 3e99ecacc9a..75b365d8500 100644 --- a/docs/scrollview/index.html +++ b/docs/scrollview/index.html @@ -16,7 +16,7 @@ ScrollView · React Native - + @@ -30,7 +30,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.

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/sectionlist/index.html b/docs/sectionlist/index.html index 39908f04857..35ec5fd0935 100644 --- a/docs/sectionlist/index.html +++ b/docs/sectionlist/index.html @@ -16,7 +16,7 @@ SectionList · React Native - + @@ -30,7 +30,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, function, 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 Class, a render function, or a rendered element.

TypeRequired
[component, function, element]No

ListFooterComponent

Rendered at the very end of the list. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
[component, function, element]No

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component Class, a render function, or a rendered element.

TypeRequired
component, function, 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, function, 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/index.html b/docs/security/index.html index 84a901647ad..da069875bcc 100644 --- a/docs/security/index.html +++ b/docs/security/index.html @@ -16,7 +16,7 @@ Security · React Native - + @@ -30,7 +30,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 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 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/index.html b/docs/segmentedcontrolios/index.html index fccac3d7e71..f3759a67d1c 100644 --- a/docs/segmentedcontrolios/index.html +++ b/docs/segmentedcontrolios/index.html @@ -16,7 +16,7 @@ 🚧 SegmentedControlIOS · React Native - + @@ -30,7 +30,7 @@

🚧 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

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/index.html b/docs/settings/index.html index 193933d1ead..62bfb64c63c 100644 --- a/docs/settings/index.html +++ b/docs/settings/index.html @@ -16,7 +16,7 @@ Settings · React Native - + @@ -30,7 +30,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/index.html b/docs/shadow-props/index.html index a2c654a5da3..1e4e50f93e6 100644 --- a/docs/shadow-props/index.html +++ b/docs/shadow-props/index.html @@ -16,7 +16,7 @@ Shadow Props · React Native - + @@ -30,7 +30,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/index.html b/docs/share/index.html index 13913fc4544..2068ff4e973 100644 --- a/docs/share/index.html +++ b/docs/share/index.html @@ -16,7 +16,7 @@ Share · React Native - + @@ -30,7 +30,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/index.html b/docs/signed-apk-android/index.html index e4b399e82ad..0ec11dfeb7b 100644 --- a/docs/signed-apk-android/index.html +++ b/docs/signed-apk-android/index.html @@ -16,7 +16,7 @@ Publishing to Google Play Store · React Native - + @@ -30,7 +30,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/index.html b/docs/slider/index.html index 15fde67911a..b63f419cd2c 100644 --- a/docs/slider/index.html +++ b/docs/slider/index.html @@ -16,7 +16,7 @@ 🚧 Slider · React Native - + @@ -30,7 +30,7 @@

🚧 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/snapshotviewios/index.html b/docs/snapshotviewios/index.html index 62c685f7178..07fc64fcfa0 100644 --- a/docs/snapshotviewios/index.html +++ b/docs/snapshotviewios/index.html @@ -16,7 +16,7 @@ SnapshotViewIOS · React Native - + @@ -30,7 +30,7 @@
Edit this page
Last updated on
- + diff --git a/docs/state/index.html b/docs/state/index.html index 72e71373b29..f6565414aab 100644 --- a/docs/state/index.html +++ b/docs/state/index.html @@ -16,7 +16,7 @@ State · React Native - + @@ -30,7 +30,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/index.html b/docs/statusbar/index.html index d217cc6fe86..88124aef323 100644 --- a/docs/statusbar/index.html +++ b/docs/statusbar/index.html @@ -16,7 +16,7 @@ StatusBar · React Native - + @@ -30,7 +30,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/index.html b/docs/statusbarios/index.html index 0be4b865b22..52878463481 100644 --- a/docs/statusbarios/index.html +++ b/docs/statusbarios/index.html @@ -16,7 +16,7 @@ 🚧 StatusBarIOS · React Native - + @@ -30,7 +30,7 @@

🚧 StatusBarIOS

Deprecated. Use StatusBar for mutating the status bar.

Edit this page
Last updated on
- + diff --git a/docs/style/index.html b/docs/style/index.html index 87c1223f70f..0e6a1b00c6a 100644 --- a/docs/style/index.html +++ b/docs/style/index.html @@ -16,7 +16,7 @@ Style · React Native - + @@ -30,7 +30,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/index.html b/docs/stylesheet/index.html index 02be5a28b2b..2237d510608 100644 --- a/docs/stylesheet/index.html +++ b/docs/stylesheet/index.html @@ -16,7 +16,7 @@ StyleSheet · React Native - + @@ -30,7 +30,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/index.html b/docs/switch/index.html index d01803ad5af..8f355315711 100644 --- a/docs/switch/index.html +++ b/docs/switch/index.html @@ -16,7 +16,7 @@ Switch · React Native - + @@ -30,7 +30,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/index.html b/docs/symbolication/index.html index bea3b35408d..0c95f155795 100644 --- a/docs/symbolication/index.html +++ b/docs/symbolication/index.html @@ -16,7 +16,7 @@ Symbolicating a stack trace · React Native - + @@ -30,7 +30,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/index.html b/docs/systrace/index.html index bd27df05ba9..675d32f1e52 100644 --- a/docs/systrace/index.html +++ b/docs/systrace/index.html @@ -16,7 +16,7 @@ Systrace · React Native - + @@ -30,7 +30,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/index.html b/docs/tabbarios-item/index.html index cc78cc0da8b..83c751459c8 100644 --- a/docs/tabbarios-item/index.html +++ b/docs/tabbarios-item/index.html @@ -16,7 +16,7 @@ TabBarIOS.Item · React Native - + @@ -30,7 +30,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/index.html b/docs/tabbarios/index.html index 6a28e15f77c..cc1db0f899a 100644 --- a/docs/tabbarios/index.html +++ b/docs/tabbarios/index.html @@ -16,7 +16,7 @@ TabBarIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/testing-overview/index.html index 716af2ecf32..024039a1cd0 100644 --- a/docs/testing-overview/index.html +++ b/docs/testing-overview/index.html @@ -16,7 +16,7 @@ Testing · React Native - + @@ -34,7 +34,7 @@
fireEvent.changeText(
getByPlaceholder('Enter grocery item'),
'banana'
);
fireEvent.press(getByText('Add the item to list'));
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:

  • For you as a developer or reviewer, it can be hard to tell whether a change in snapshot is intended or whether it's evidence of a bug. Especially large snapshots can quickly become hard to understand and their added value becomes low.
  • When snapshot is created, at that point it is considered to be correct-even in the case when the rendered output is actually wrong.
  • When a snapshot fails, it's tempting to update it using the --updateSnapshot jest option without taking proper care to investigate whether the change is expected. Certain developer discipline is thus needed.

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:

  • writing them is more time consuming compared to the other types of tests
  • they are slower to run
  • they are more prone to flakiness (a "flaky" test is a test which randomly passes and fails without any change to code)

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/index.html b/docs/text-style-props/index.html index 8380296fcfe..9ca9df8bec8 100644 --- a/docs/text-style-props/index.html +++ b/docs/text-style-props/index.html @@ -16,7 +16,7 @@ Text Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/text/index.html index fe235a2bf03..e429dc36413 100644 --- a/docs/text/index.html +++ b/docs/text/index.html @@ -16,7 +16,7 @@ Text · React Native - + @@ -34,7 +34,7 @@
// otherwise, the text will flow in its own block
// |First part |
// |and |
// |second part|

Limited Style Inheritance

On the web, the usual way to set a font family and size for the entire document is to take advantage of inherited CSS properties like so:

html {
font-family: 'lucida grande', tahoma, verdana, arial, sans-serif;
font-size: 11px;
color: #141823;
}

All elements in the document will inherit this font unless they or one of their parents specifies a new rule.

In React Native, we are more strict about it: you must wrap all the text nodes inside of a <Text> component. You cannot have a text node directly under a <View>.

// BAD: will raise exception, can't have a text node as child of a <View>
<View>
Some text
</View>
// 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:

  • (Developer) React components are designed with strong isolation in mind: You should be able to drop a component anywhere in your application, trusting that as long as the props are the same, it will look and behave the same way. Text properties that could inherit from outside of the props would break this isolation.

  • (Implementor) The implementation of React Native is also simplified. We do not need to have a fontFamily field on every single element, and we do not need to potentially traverse the tree up to the root every time we display a text node. The style inheritance is only encoded inside of the native Text component and doesn't leak to other components or the system itself.

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:

  • 'none' - The element has no role.
  • 'button' - The element should be treated as a button.
  • 'link' - The element should be treated as a link.
  • 'header' - The element is a header that divides content into sections.
  • 'search' - The element should be treated as a search field.
  • 'image' - The element should be treated as an image.
  • 'key' - The element should be treated like a keyboard key.
  • 'text' - The element should be treated as text.
  • 'summary' - The element provides app summary information.
  • 'imagebutton' - The element has the role of both an image and also a button.
  • 'adjustable' - The element allows adjustment over a range of values.

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:

  • 'selected' - The element is in a selected state.
  • 'disabled' - The element is in a disabled state.
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.

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:

  • 'phoneNumber'
  • 'link'
  • 'email'
  • 'none'
  • 'all'
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:

  • head - The line is displayed so that the end fits in the container and the missing text at the beginning of the line is indicated by an ellipsis glyph. e.g., "...wxyz"
  • middle - The line is displayed so that the beginning and end fit in the container and the missing text in the middle is indicated by an ellipsis glyph. "ab...yz"
  • tail - The line is displayed so that the beginning fits in the container and the missing text at the end of the line is indicated by an ellipsis glyph. e.g., "abcd..."
  • clip - Lines are not drawn past the edge of the text container.

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:

  • 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

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
  • TextLayoutEvent - SyntheticEvent object that contains a key called lines with a value which is an array containing objects with the following properties
    • { x: number, y: number, width: number, height: number, ascender: number, capHeight: number, descender: number, text: string, xHeight: number,}

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/index.html b/docs/textinput/index.html index 974b10d934a..1fcb5933639 100644 --- a/docs/textinput/index.html +++ b/docs/textinput/index.html @@ -16,7 +16,7 @@ TextInput · React Native - + @@ -30,7 +30,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=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/timepickerandroid/index.html b/docs/timepickerandroid/index.html index bb3e87c6c2e..05f4458015d 100644 --- a/docs/timepickerandroid/index.html +++ b/docs/timepickerandroid/index.html @@ -16,7 +16,7 @@ 🚧 TimePickerAndroid · React Native - + @@ -30,7 +30,7 @@

🚧 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/timers/index.html b/docs/timers/index.html index ac912080728..61bb2cc0185 100644 --- a/docs/timers/index.html +++ b/docs/timers/index.html @@ -16,7 +16,7 @@ Timers · React Native - + @@ -30,7 +30,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/index.html b/docs/toastandroid/index.html index 5e8c92a9e47..d54f0e654fe 100644 --- a/docs/toastandroid/index.html +++ b/docs/toastandroid/index.html @@ -16,7 +16,7 @@ ToastAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/toolbarandroid/index.html index 3d84253dc4c..e2d4de31904 100644 --- a/docs/toolbarandroid/index.html +++ b/docs/toolbarandroid/index.html @@ -16,7 +16,7 @@ ToolbarAndroid · React Native - + @@ -30,7 +30,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/index.html b/docs/touchablehighlight/index.html index 131325f0ea6..e848e8ea5e6 100644 --- a/docs/touchablehighlight/index.html +++ b/docs/touchablehighlight/index.html @@ -16,7 +16,7 @@ TouchableHighlight · React Native - + @@ -31,7 +31,7 @@

TouchableHighlight

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, 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.

function MyComponent(props) {
return (
<View {...props} style={{ flex: 1, backgroundColor: '#fff' }}>
<Text>My Component</Text>
</View>
);
}
<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/index.html b/docs/touchablenativefeedback/index.html index ac361c4d3f0..46d602b5c24 100644 --- a/docs/touchablenativefeedback/index.html +++ b/docs/touchablenativefeedback/index.html @@ -16,7 +16,7 @@ TouchableNativeFeedback · React Native - + @@ -30,7 +30,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/index.html b/docs/touchableopacity/index.html index aa8b0c73845..e4c893147ab 100644 --- a/docs/touchableopacity/index.html +++ b/docs/touchableopacity/index.html @@ -16,7 +16,7 @@ TouchableOpacity · React Native - + @@ -30,7 +30,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

Methods

setOpacityTo()

setOpacityTo((value: number), (duration: number));

Animate the touchable to a new opacity.

Edit this page
Last updated on
- + diff --git a/docs/touchablewithoutfeedback/index.html b/docs/touchablewithoutfeedback/index.html index 70455660430..ee3ddc48a05 100644 --- a/docs/touchablewithoutfeedback/index.html +++ b/docs/touchablewithoutfeedback/index.html @@ -16,7 +16,7 @@ TouchableWithoutFeedback · React Native - + @@ -31,7 +31,7 @@

TouchableWithoutFeedback

If you're looking for a more extensive and future-proof way to handle touch-based input, check out the Pressable API.

Do not use unless you have a very good reason. All elements that respond to press should have a visual feedback when touched.

TouchableWithoutFeedback supports only one child. If you wish to have several child components, wrap them in a View. Importantly, TouchableWithoutFeedback works by cloning its child and applying responder props to it. It is therefore required that any intermediary components pass through those props to the underlying React Native component.

Usage Pattern

function MyComponent(props) {
return (
<View {...props} style={{ flex: 1, backgroundColor: '#fff' }}>
<Text>My Component</Text>
</View>
);
}
<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:

  • '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

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/index.html b/docs/transforms/index.html index 7e049a932b5..7e42963b52e 100644 --- a/docs/transforms/index.html +++ b/docs/transforms/index.html @@ -16,7 +16,7 @@ Transforms · React Native - + @@ -30,7 +30,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/index.html b/docs/troubleshooting/index.html index b89126d29ec..052ad01998d 100644 --- a/docs/troubleshooting/index.html +++ b/docs/troubleshooting/index.html @@ -16,7 +16,7 @@ Troubleshooting · React Native - + @@ -30,7 +30,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/index.html b/docs/tutorial/index.html index 8ba8da56014..661f6be02af 100644 --- a/docs/tutorial/index.html +++ b/docs/tutorial/index.html @@ -16,7 +16,7 @@ Learn the Basics · React Native - + @@ -42,7 +42,7 @@
return (
<View style={styles.container}>
<Text>You clicked {count} times</Text>
<Button
onPress={() => setCount(count + 1)}
title="Click me!"
/>
</View>
);
};
// 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/index.html b/docs/typescript/index.html index 61160ee46a9..a2a04d2bde5 100644 --- a/docs/typescript/index.html +++ b/docs/typescript/index.html @@ -16,7 +16,7 @@ Using TypeScript · React Native - + @@ -38,7 +38,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'
}
});
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. 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/upgrading/index.html b/docs/upgrading/index.html index 0bae9b6261a..3f025378d27 100644 --- a/docs/upgrading/index.html +++ b/docs/upgrading/index.html @@ -16,7 +16,7 @@ Upgrading to new React Native versions · React Native - + @@ -30,7 +30,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/index.html b/docs/usecolorscheme/index.html index 24ece7f7e2e..4e0d7fe3cfa 100644 --- a/docs/usecolorscheme/index.html +++ b/docs/usecolorscheme/index.html @@ -16,7 +16,7 @@ useColorScheme · React Native - + @@ -31,7 +31,7 @@

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.
import { Text, useColorScheme } from 'react-native';
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/index.html b/docs/usewindowdimensions/index.html index a19f554c9ea..e1152efd28f 100644 --- a/docs/usewindowdimensions/index.html +++ b/docs/usewindowdimensions/index.html @@ -16,7 +16,7 @@ useWindowDimensions · React Native - + @@ -30,7 +30,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/index.html b/docs/using-a-listview/index.html index 9ed1f0b719e..a7b3ba5bb6e 100644 --- a/docs/using-a-listview/index.html +++ b/docs/using-a-listview/index.html @@ -16,7 +16,7 @@ Using List Views · React Native - + @@ -30,7 +30,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/index.html b/docs/using-a-scrollview/index.html index fd8846e6ef2..c54e0bb9347 100644 --- a/docs/using-a-scrollview/index.html +++ b/docs/using-a-scrollview/index.html @@ -16,7 +16,7 @@ Using a ScrollView · React Native - + @@ -30,7 +30,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/index.html b/docs/vibration/index.html index 2bd43212d05..95ee0be4a21 100644 --- a/docs/vibration/index.html +++ b/docs/vibration/index.html @@ -16,7 +16,7 @@ Vibration · React Native - + @@ -30,7 +30,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/index.html b/docs/vibrationios/index.html index 9b1ba0567c4..0fe249bcd04 100644 --- a/docs/vibrationios/index.html +++ b/docs/vibrationios/index.html @@ -16,7 +16,7 @@ VibrationIOS · React Native - + @@ -30,7 +30,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/index.html b/docs/view-style-props/index.html index bd7661678a1..3c71ba5f6a6 100644 --- a/docs/view-style-props/index.html +++ b/docs/view-style-props/index.html @@ -16,7 +16,7 @@ View Style Props · React Native - + @@ -30,7 +30,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/index.html b/docs/view/index.html index 90dafed82f1..00a285d4089 100644 --- a/docs/view/index.html +++ b/docs/view/index.html @@ -16,7 +16,7 @@ View · React Native - + @@ -30,7 +30,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/index.html b/docs/viewpagerandroid/index.html index bb0dc9bb28f..d5d16e3f180 100644 --- a/docs/viewpagerandroid/index.html +++ b/docs/viewpagerandroid/index.html @@ -16,7 +16,7 @@ 🚧 ViewPagerAndroid · React Native - + @@ -32,7 +32,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.

  • '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

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:

  • position - index of first page from the left that is currently visible
  • offset - value from range [0, 1] describing stage between page transitions. Value x means that (1 - x) fraction of the page at "position" index is visible, and x fraction of the next page is visible.
TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

  • idle, meaning there is no interaction with the page scroller happening at the time
  • dragging, meaning there is currently an interaction with the page scroller
  • settling, meaning that there was an interaction with the page scroller, and the page scroller is now finishing its closing or opening animation
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:

  • position - index of page that has been selected
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.

  • position - index of page that will be selected
TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

  • position - index of page that will be selected
TypeRequired
NumberYes

Type Definitions

ViewPagerScrollState

Type
\$Enum

Constants:

ValueDescription
idle
dragging
settling
Edit this page
Last updated on
- + diff --git a/docs/virtualizedlist/index.html b/docs/virtualizedlist/index.html index cc059655444..da1edc03e59 100644 --- a/docs/virtualizedlist/index.html +++ b/docs/virtualizedlist/index.html @@ -16,7 +16,7 @@ VirtualizedList · React Native - + @@ -33,7 +33,7 @@
- 'animated' (boolean). Optional default is true.

scrollToIndex()

scrollToIndex((params: object));

Valid params consist of:

  • 'animated' (boolean). Optional.
  • 'index' (number). Required.
  • 'viewOffset' (number). Optional.
  • 'viewPosition' (number). Optional.

scrollToItem()

scrollToItem((params: object));

Valid params consist of:

  • 'animated' (boolean). Optional.
  • 'item' (Item). Required.
  • 'viewPosition' (number). Optional.

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:

  • 'virtualizedList' (Object). This object consist of the following
    • getScrollMetrics' (Function). Returns an object with following properties: { contentLength: number, dOffset: number, dt: number, offset: number, timestamp: number, velocity: number, visibleLength: number }.
    • 'horizontal' (boolean) - Optional.
    • 'getOutermostParentListRef' (Function).
    • 'getNestedChildState' (Function) - Returns ChildListState .
    • 'registerAsNestedChild' (Function). This accept an object with following properties { cellKey: string, key: string, ref: VirtualizedList, parentDebugInfo: ListDebugInfo }. It returns a ChildListState
    • 'unregisterAsNestedChild' (Function). This takes an object with following properties, { key: string, state: ChildListState }
    • 'debugInfo' (ListDebugInfo).

hasMore()

hasMore () => boolean;
Edit this page
Last updated on
- + diff --git a/docs/webview/index.html b/docs/webview/index.html index 4ce1cc1c035..c55c8e970ca 100644 --- a/docs/webview/index.html +++ b/docs/webview/index.html @@ -16,7 +16,7 @@ 🚧 WebView · React Native - + @@ -32,7 +32,7 @@
class MyWeb extends Component {
render() {
return (
<WebView
source={{
uri: 'https://github.com/facebook/react-native'
}}
style={{ marginTop: 20 }}
/>
);
}
}

Minimal example with inline HTML:

import React, { Component } from 'react';
import { WebView } from 'react-native';
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

  • uri (string) - The URI to load in the WebView. Can be a local or remote file.
  • method (string) - The HTTP Method to use. Defaults to GET if not specified. On Android, the only supported methods are GET and POST.
  • headers (object) - Additional HTTP headers to send with the request. On Android, this can only be used with GET requests.
  • body (string) - The 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. On Android, this can only be used with POST requests.

Static HTML

  • html (string) - A static HTML page to display in the WebView.
  • baseUrl (string) - The base URL to be used for any relative links in the 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:

  • component (any)
  • props (object)
  • viewManager (object)
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:

  • normal: 0.998
  • fast: 0.99 (the default for iOS web view)
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:

  • never (default) - WebView will not allow a secure origin to load content from an insecure origin.
  • always - WebView will allow a secure origin to load content from any other origin, even if that origin is insecure.
  • compatibility - WebView will attempt to be compatible with the approach of a modern web browser with regard to mixed content.
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:

  • phoneNumber
  • link
  • address
  • calendarEvent
  • none
  • all

With the new WebKit implementation, we have three new values:

  • trackingNumber
  • flightNumber
  • lookupSuggestion
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/index.html b/help/index.html index e636e806cfc..ecaa7f5a8c6 100644 --- a/help/index.html +++ b/help/index.html @@ -16,7 +16,7 @@ Community · React Native - + @@ -27,7 +27,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 7293a1a287d..3217af14499 100644 --- a/index.html +++ b/index.html @@ -16,12 +16,12 @@ React Native · A framework for building native apps using React - + - +
@@ -56,13 +56,13 @@ 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
  • Coinbase
  • Shopify
  • Tableau
  • Oculus
  • Skype
  • Discord
  • Bloomberg
  • Pinterest
  • Tesla
  • Uber Eats
  • Walmart
  • Wix.com
  • Salesforce
  • 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
  • Coinbase
  • Shopify
  • Tableau
  • Oculus
  • Skype
  • Discord
  • Bloomberg
  • Pinterest
  • Tesla
  • Uber Eats
  • Walmart
  • Wix.com
  • Salesforce
  • Artsy
  • Tencent QQ

and many more.

Give it a try

  1. Run this

    npx react-native init MyTestApp

  2. Read these

    Get startedLearn basics
- + - + \ No newline at end of file diff --git a/runtime~main.67295741.js b/runtime~main.0980136f.js similarity index 99% rename from runtime~main.67295741.js rename to runtime~main.0980136f.js index 69672fd7261..1ea80cb7c3b 100644 --- a/runtime~main.67295741.js +++ b/runtime~main.0980136f.js @@ -1 +1 @@ -!function(d){function c(c){for(var f,r,t=c[0],n=c[1],o=c[2],u=0,l=[];uSearch the documentation · React Native - + @@ -28,7 +28,7 @@

Search the documentation

- + diff --git a/showcase/index.html b/showcase/index.html index 36b437d787c..3719b75d8aa 100644 --- a/showcase/index.html +++ b/showcase/index.html @@ -16,7 +16,7 @@ Who's using React Native? · React Native - + @@ -26,7 +26,7 @@

Who's using React Native?

Thousands of apps are using React Native, from established Fortune 500 companies to hot new startups. If you're curious to see what can be accomplished with React Native, check out these apps!

Facebook Analytics

Facebook Analytics

Android • iOS

Oculus

Oculus

Android • iOS

Skype

Skype

Android • iOS

Tesla

Tesla

Android • iOS

Vogue

Vogue

iOS

Fill out this form to apply to the customer spotlight.

A curated list of open source React Native apps is also being kept by Infinite Red.

- + diff --git a/versions/index.html b/versions/index.html index 567c50d4aef..c9d2ff8a034 100644 --- a/versions/index.html +++ b/versions/index.html @@ -16,7 +16,7 @@ React Native - + @@ -27,7 +27,7 @@

React Native versions

Open source React Native releases follow a monthly release train that is coordinated on GitHub through the react-native-releases repository. At the beginning of each month, a new release candidate is created off the master branch of facebook/react-native. The release candidate will soak for a month to allow contributors like yourself to verify the changes and to identify any issues by writing clear, actionable bug reports. Eventually, the release candidate will be promoted to stable.

Latest versions

To see what changes are coming and provide better feedback to React Native contributors, use the latest release candidate when possible. Changes introduced in a release candidate will have been shipped to production Facebook apps for over two weeks by the time the release candidate is cut.

MasterDocumentationCommits since 0.63

Stable versions

The most recent stable version will be used automatically whenever a new project is created using the react-native init command.

0.63DocumentationChangelog
0.62DocumentationChangelog
0.61DocumentationChangelog
0.60DocumentationChangelog

Archived versions

The documentation for versions below 0.60 can be found on the separate website called React Native Archive.

- +