@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('browserPageLoaded', () => {
    console.log("browser was loaded.");
});

Remove All Listeners

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

API

• openInWebView(...)
• openInSystemBrowser(...)
• openInExternalBrowser(...)
• close()
• addListener('browserClosed' | 'browserPageLoaded', ...)
• 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 event.

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

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

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

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. This will be a minimum of 50% of the screen's height. If no value is passed, we 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> |

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 |