📄 README.md

@capacitor/inappbrowser

The InAppBrowser Plugin provides a web browser view that allows you to load any web page externally. It behaves as a standard web browser and is useful to load untrusted content without risking your application's security. It offers three different ways to open URLs; in a WebView, in an in-app system browser (Custom Tabs for Android and SFSafariViewController for iOS), and in the device's default browser.

Install

npm install @capacitor/inappbrowser
npx cap sync

Supported Platforms

iOS
Android

Android

The InAppBrowser plugin requires a minimum Android SDK target of 26. This is higher than the default that comes with your Capacitor application. You can update this value in your android/variables.gradle file.

ext {
    minSdkVersion = 26
}

Usage Example

Open In External Browser

import { InAppBrowser } from '@capacitor/inappbrowser';
await InAppBrowser.openInExternalBrowser({
    url: "https://www.google.com"
});

Open In System Browser (Custom Tabs for Android, SFSafariViewController for iOS)

import { InAppBrowser, DefaultSystemBrowserOptions } from '@capacitor/inappbrowser';
await InAppBrowser.openInSystemBrowser({
    url: "https://www.google.com",
    options: DefaultSystemBrowserOptions
});

Open In Web View

import { InAppBrowser, DefaultWebViewOptions } from '@capacitor/inappbrowser';
await InAppBrowser.openInWebView({
    url: "https://www.google.com",
    options: DefaultWebViewOptions
});

Close (Web View or System Browser)

import { InAppBrowser } from '@capacitor/inappbrowser';
await InAppBrowser.close();

Add Listeners

import { InAppBrowser } from '@capacitor/inappbrowser';
await InAppBrowser.addListener('browserClosed', () => {
    console.log("browser was closed.");
});

await InAppBrowser.addListener('browserPageNavigationCompleted', (data) => {
    console.log("browser page navigation was completed. " + data.url);
});

await InAppBrowser.addListener('browserPageLoaded', () => {
    console.log("browser was loaded.");
});

Remove All Listeners

import { InAppBrowser } from '@capacitor/inappbrowser';
InAppBrowser.removeAllListeners();

API

openInWebView(...)
openInSystemBrowser(...)
openInExternalBrowser(...)
close()
addListener('browserClosed' | 'browserPageLoaded', ...)
addListener('browserPageNavigationCompleted', ...)
removeAllListeners()
Interfaces
Enums

openInWebView(...)

openInWebView(model: OpenInWebViewParameterModel) => Promise<void>

Opens the web content of the given URL in your mobile app using a custom web view within your application.

Param	Type	Description
`model`	`OpenInWebViewParameterModel`	The parameters to open the URL in the web view

openInSystemBrowser(...)

openInSystemBrowser(model: OpenInSystemBrowserParameterModel) => Promise<void>

Opens the web content of the given URL in your mobile app, using SafariViewController for iOS and Custom Tabs for Android.

Param	Type	Description
`model`	`OpenInSystemBrowserParameterModel`	The parameters to open the URL in the system browser

openInExternalBrowser(...)

openInExternalBrowser(model: OpenInDefaultParameterModel) => Promise<void>

Opens the web content of the given URL in a separate browser, outside of your mobile application.

Param	Type	Description
`model`	`OpenInDefaultParameterModel`	The parameters to open the URL in the external browser

close()

close() => Promise<void>

Closes the currently active browser. It can be used to close browsers launched through the openInSystemBrowser or openInWebView actions.

addListener('browserClosed' | 'browserPageLoaded', ...)

addListener(eventName: "browserClosed" | "browserPageLoaded", listenerFunc: () => void) => Promise<PluginListenerHandle>

Adds a listener for the specified browser events, with no data being returned.

Param	Type	Description
`eventName`	`'browserClosed' \`	'browserPageLoaded'	The name of the browser event to listen for: 'browserClosed' or 'browserPageLoaded'.
`listenerFunc`	`() => void`	The function to be called when the event occurs.

Returns: Promise<PluginListenerHandle>

addListener('browserPageNavigationCompleted', ...)

addListener(eventName: "browserPageNavigationCompleted", listenerFunc: (data: BrowserPageNavigationCompletedEventData) => void) => Promise<PluginListenerHandle>

Adds a listener for the specified browser event, which receives data.

Param	Type	Description
`eventName`	`'browserPageNavigationCompleted'`	The name of the browser event to listen for: 'browserPageNavigationCompleted'. Applies only to openInWebView.
`listenerFunc`	`(data: BrowserPageNavigationCompletedEventData) => void`	The function to be called when the event occurs.

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => void

Removes all listeners for the browser events.

Interfaces

OpenInWebViewParameterModel

Defines the options for opening a URL in the web view.

Prop	Type	Description
`options`	`WebViewOptions`	A structure containing some configurations to apply to the Web View.
`customHeaders`	`{ [key: string]: string; }`	A map of custom headers to be sent with the request.

WebViewOptions

Prop	Type	Description
`showURL`	`boolean`	Displays the URL on the Web View.
`showToolbar`	`boolean`	Displays the toolbar on the Web View.
`clearCache`	`boolean`	Clears the Web View's cookie cache before a new window is opened.
`clearSessionCache`	`boolean`	Clears the session cookie cache before a new window is opened.
`mediaPlaybackRequiresUserAction`	`boolean`	Prevents HTML5 audio or video from auto-playing.
`closeButtonText`	`string`	Sets the text to display on the Close button on the Web View.
`toolbarPosition`	`ToolbarPosition`	Sets the position to display the Toolbar on the Web View.
`showNavigationButtons`	`boolean`	Displays the navigation buttons.
`leftToRight`	`boolean`	Swaps the positions of the navigation buttons and the close button.
`customWebViewUserAgent`	`string \`	null	Sets a custom user agent to open the Web View with. If empty or not set, the parameter will be ignored.
`android`	`AndroidWebViewOptions`	Android-specific Web View options.
`iOS`	`iOSWebViewOptions`	iOS-specific Web View options.

AndroidWebViewOptions

Prop	Type	Description
`allowZoom`	`boolean`	Shows the Android browser's zoom controls.
`hardwareBack`	`boolean`	Uses the hardware back button to navigate backwards through the Web View's history. If there is no previous page, the Web View will close.
`pauseMedia`	`boolean`	Makes the Web View pause/resume with the app to stop background audio.

iOSWebViewOptions

Prop	Type	Description
`allowOverScroll`	`boolean`	Turns on the Web View bounce property.
`enableViewportScale`	`boolean`	Prevents viewport scaling through a meta tag.
`allowInLineMediaPlayback`	`boolean`	Allows in-line HTML5 media playback, displaying within the browser window rather than a device-specific playback interface. Note: The HTML's video element must also include the webkit-playsinline attribute.
`surpressIncrementalRendering`	`boolean`	Waits until all new view content is received before being rendered.
`viewStyle`	`iOSViewStyle`	Sets the presentation style of the Web View.
`animationEffect`	`iOSAnimation`	Sets the transition style of the Web View.
`allowsBackForwardNavigationGestures`	`boolean`	Enables back and forward swipe gestures in the Web View.

OpenInSystemBrowserParameterModel

Defines the options for opening a URL in the system browser.

Prop	Type	Description
`options`	`SystemBrowserOptions`	A structure containing some configurations to apply to the System Browser.

SystemBrowserOptions

Prop	Type	Description
`android`	`AndroidSystemBrowserOptions`	Android-specific System Browser options.
`iOS`	`iOSSystemBrowserOptions`	iOS-specific System Browser options.

AndroidSystemBrowserOptions

Prop	Type	Description
`showTitle`	`boolean`	Enables the title display.
`hideToolbarOnScroll`	`boolean`	Hides the toolbar when scrolling.
`viewStyle`	`AndroidViewStyle`	Sets the presentation style of CustomTabs.
`bottomSheetOptions`	`AndroidBottomSheet`	Sets the options for the bottom sheet when this is selected as the viewStyle. If viewStyle is FULL_SCREEN, this will be ignored.
`startAnimation`	`AndroidAnimation`	Sets the start animation for when the browser appears.
`exitAnimation`	`AndroidAnimation`	Sets the exit animation for when the browser disappears.

AndroidBottomSheet

Prop	Type	Description
`height`	`number`	Sets the height of the bottom sheet, in pixels. Custom tabs will set the bottom height to at least 50% of the screen. If no value is passed, it will default to the minimum value.
`isFixed`	`boolean`	Sets whether the bottom sheet is fixed.

iOSSystemBrowserOptions

Prop	Type	Description
`closeButtonText`	`DismissStyle`	Sets a text to use as the close button's caption.
`viewStyle`	`iOSViewStyle`	Sets the presentation style of SafariViewController.
`animationEffect`	`iOSAnimation`	Sets the transition style of SafariViewController.
`enableBarsCollapsing`	`boolean`	Enables bars to collapse on scrolling down.
`enableReadersMode`	`boolean`	Enables readers mode.

OpenInDefaultParameterModel

Defines the options for opening a URL in the external browser and used by the others.

Prop	Type	Description
`url`	`string`	The URL to be opened. It must contain either 'http' or 'https' as the protocol prefix.

PluginListenerHandle

Prop	Type
`remove`	`() => Promise<void>`

BrowserPageNavigationCompletedEventData

Defines the data for the 'browserPageNavigationCompleted' event.

Prop	Type	Description
`url`	`string`	The URL of the page that was loaded.

Enums

ToolbarPosition

Members
`TOP`
`BOTTOM`

iOSViewStyle

Members
`PAGE_SHEET`
`FORM_SHEET`
`FULL_SCREEN`

iOSAnimation

Members
`FLIP_HORIZONTAL`
`CROSS_DISSOLVE`
`COVER_VERTICAL`

AndroidViewStyle

Members
`BOTTOM_SHEET`
`FULL_SCREEN`

AndroidAnimation

Members
`FADE_IN`
`FADE_OUT`
`SLIDE_IN_LEFT`
`SLIDE_OUT_RIGHT`

DismissStyle

Members
`CLOSE`
`CANCEL`
`DONE`