@matt-block/react-native-in-app-browser

React Native In-App Browser

In-App browser support for React Native, using Chrome Custom Tabs on Android and Safari View Controller on iOS.

Compatibility

⚠️Support has ended on October 1st 2020.

It is recommended migrating to react-native-inappbrowser-reborn for continued support and more features.

React Native	Library	Status	End-of-Life
0.60.0 - 0.62.x		EOL	2020-10-01
0.57.x - 0.59.x		EOL	2020-01-03
0.57.x - 0.59.5		EOL	2019-06-09

Using Expo? Check out WebBrowser.

Installation

Install the package via Yarn or npm:

yarn add @matt-block/react-native-in-app-browser

# or
npm install --save @matt-block/react-native-in-app-browser

Linking

React Native 0.60.0 and later

Packages are autolinked, however an extra step for iOS projects is needed:

cd ios && pod install && cd ..

React Native 0.59.x and below

Manually link the native module to your project:

react-native link @matt-block/react-native-in-app-browser

Note for iOS projects

In order for Xcode projects to build when using Swift-based libraries, your main app project must contain Swift code and a bridging header. If your app project does not contain any Swift code, add a single empty .swift file and an empty bridging header to your app.

If your Xcode project already makes use of Swift code you can safely ignore this note.

Usage

⚠️ Still using an older version ? Check out the migration guides.

import { InAppBrowser } from "@matt-block/react-native-in-app-browser";


// Minimal setup.
InAppBrowser.open("https://www.wikipedia.org/").catch(error => {
  console.log(error);
});


// With platform-specific optional settings.
InAppBrowser.open("https://www.wikipedia.org/", {
  android: {
    //...,
  },
  ios: {
    //...,
  },
}).catch(error => {
  console.log(error);
});


// Using async/await.
async onClickHandler() {
  try {
    await InAppBrowser.open("https://www.wikipedia.org/");
  } catch (error) {
    console.log(error);
  }
}

Startup optimizations (Android only)

Chrome Custom Tabs exposes methods to reduce the start time of a custom tab activity.

For information on how these work, check Custom Tabs - Example and Usage Optimization

import { InAppBrowser } from "@matt-block/react-native-in-app-browser";

InAppBrowser.warmup();
InAppBrowser.mayLaunchUrl("https://wikipedia.org");

Programmatically close (iOS only)

It is possible to manually dismiss the iOS in-app instance by calling the method close.

import { InAppBrowser } from "@matt-block/react-native-in-app-browser";

InAppBrowser.close();

This is not possible on Android since Chrome Custom Tabs do not expose such functionality and Activity workarounds would bring this package way out of scope.

Settings

The main method open accepts an object with settings objects for each platform:

import { InAppBrowser } from "@matt-block/react-native-in-app-browser";

InAppBrowser.open("https://www.wikipedia.org/", {
  android: {},
  ios: {}
});

Settings can also be initialized separately with configure so that each open call won't need to specify them each time:

import { InAppBrowser } from "@matt-block/react-native-in-app-browser";

// Somewhere in your app initialization logic.
InAppBrowser.configure({
  android: {},
  ios: {}
});

// Other part of your code base.
// Previously initialized settings will apply.
InAppBrowser.open("https://www.wikipedia.org/");

Note that open will still accept settings as always but will effectively perform a merge between the initialized properties and the provided settings object (which will have priority over the initialized properties):

import { InAppBrowser } from "@matt-block/react-native-in-app-browser";

// Somewhere in your app initialization logic.
InAppBrowser.configure({
  android: {
    toolbarColor: "red",
    showTitle: true
  }
});

// Other part of your code base.
// Merged settings for this call will result in:
//
// - toolbarColor: "blue",
// - showTitle: true
InAppBrowser.open("https://www.wikipedia.org/", {
  android: {
    toolbarColor: "blue"
  }
});

The properties for each platform settings are described below.

Android

Each setting is optional. Furthermore, settings with invalid values will be ignored and their default values will be used.

Setting	Type	Default	Description
toolbarColor	string	undefined	The color to tint the background of the toolbar. Provided color can be in any @ctrl/tinycolor supported format.
showTitle	boolean	false	Flag to toggle if the page title should be shown in the custom tab.
closeButtonIcon	string (as resolved by importing an image file)	undefined	Custom close button icon. Provided icon must be a .png, .jpg, or .gif file.
addDefaultShareMenu	boolean	false	Flag to toggle the default share menu.

iOS

Each setting is optional. Furthermore, settings with invalid values will be ignored and their default values will be used. Also, settings that are not supported by the iOS version at runtime will be ignored as well.

Setting	Type	Default	Description
preferredBarTintColor	string	undefined	The color to tint the background of the navigation bar and the toolbar. Provided color can be in any @ctrl/tinycolor supported format. Available on: iOS >= 10.0.
preferredControlTintColor	string	undefined	The color to tint the control buttons on the navigation bar and the toolbar. Provided color can be in any @ctrl/tinycolor supported format. Available on: iOS >= 10.0.
barCollapsingEnabled	boolean	true	Available on: iOS >= 11.0.
dismissButtonStyle	string	undefined	Available on: iOS >= 11.0.
entersReaderIfAvailable	boolean	false	A value that specifies whether Safari should enter Reader mode, if it is available. Available on: iOS >= 11.0.

Example

An example project showcasing the various configurations can be found in the example directory. Simply clone this repository, navigate into example, install the dependencies and run the app.

git clone https://github.com/matei-radu/react-native-in-app-browser.git
cd react-native-in-app-browser/example
yarn install
yarn start
yarn android # or yarn ios

License

Copyright (c) 2018-2020 Matei Bogdan Radu.

This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree.