Skip to content

in-app-browser

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

in-app-browser

README.md

Capacitor In-App Browser Plugin

Capacitor plugin to open URLs in the external browser, the system browser or an embedded web view.

Features

The Capacitor In-App Browser plugin is one of the most complete in-app browsing solutions for Capacitor apps. Here are some of the key features:

  • 🌐 Three browser modes: Open URLs in the external browser, the system browser (Custom Tabs on Android, SFSafariViewController on iOS) or an embedded web view.
  • 🧭 Navigation events: Get notified when the browser is closed, a page has been loaded or a navigation has been completed.
  • 💉 JavaScript execution: Execute any JavaScript code in the embedded web view.
  • 💬 Messaging: Exchange messages between your app and the web page in both directions.
  • 🎨 Toolbar theming: Customize the toolbar color, title, close button and navigation buttons.
  • 🍪 Session control: Clear the cache and cookies, or use an isolated data store on iOS.
  • 🎥 Media permissions: Camera and microphone permission requests from web pages are forwarded to the app.
  • 🤝 Compatibility: Works alongside the App Launcher, OAuth and System WebView plugins.
  • 📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
  • 🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

The In-App Browser plugin is typically used whenever an app needs to display web content without losing the user, for example:

  • External links: Open links, terms of service, or documentation in the system browser without leaving the app context.
  • Login and checkout flows: Open a web-based flow in the embedded web view and watch for a redirect using the browserUrlChanged event.
  • Hybrid web content: Embed a web page with a themed native toolbar and exchange messages between the app and the page.
  • Background loading: Load a URL in a hidden web view with the visible option and present it once the page has loaded.
  • Session control: Clear the cache and cookies of the web view, or use an isolated data store on iOS.

Compatibility

Plugin Version Capacitor Version Status
0.x.x >=8.x.x Active support

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-in-app-browser` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome/capacitor-in-app-browser
npx cap sync

Android

Variables

This plugin will use the following project variables (defined in your app’s variables.gradle file):

  • $androidxBrowserVersion version of androidx.browser:browser (default: 1.9.0)

Permissions

If web pages opened in the embedded web view should be able to access the camera or microphone, the following elements must be added to your AndroidManifest.xml before or after the application tag:

<!-- Required if web pages should be able to access the camera. -->
<uses-permission android:name="android.permission.CAMERA" />
<!-- Required if web pages should be able to access the microphone. -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />

The permissions must also be granted before a web page requests access to the camera or microphone.

iOS

Privacy Descriptions

If web pages opened in the embedded web view should be able to access the camera or microphone, the NSCameraUsageDescription and NSMicrophoneUsageDescription keys must be added to the Info.plist file of your app:

<key>NSCameraUsageDescription</key>
<string>The camera is used by websites opened in the in-app browser.</string>
<key>NSMicrophoneUsageDescription</key>
<string>The microphone is used by websites opened in the in-app browser.</string>

Configuration

No configuration required for this plugin.

Usage

The following examples show how to open URLs in the external, system, and in-app browsers, control the embedded web view, exchange messages with the loaded page, clear browsing data, and listen for browser events.

Open a URL in the external browser

Open a URL in the default browser app of the device. Since the browser is opened in a separate app, no events are emitted in this mode:

import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const openInExternalBrowser = async () => {
  await InAppBrowser.openInExternalBrowser({
    url: 'https://capawesome.io',
  });
};

Open a URL in the system browser

Open a URL in the system browser (Custom Tabs on Android, SFSafariViewController on iOS) and customize the toolbar with platform-specific options. Only available on Android and iOS:

import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const openInSystemBrowser = async () => {
  await InAppBrowser.openInSystemBrowser({
    url: 'https://capawesome.io',
    android: {
      showTitle: true,
      toolbarColor: '#008080',
    },
    ios: {
      dismissButtonStyle: 'close',
      toolbarColor: '#008080',
    },
  });
};

Open a URL in an embedded web view

Open a URL in an embedded web view with a native toolbar whose color, title, and buttons can be customized. Only available on Android and iOS:

import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const openInWebView = async () => {
  await InAppBrowser.openInWebView({
    url: 'https://capawesome.io',
    toolbar: {
      backgroundColor: '#008080',
      color: '#FFFFFF',
      showNavigationButtons: true,
    },
  });
};

Close the browser

Close the currently open browser. This closes browsers opened with openInWebView(...) or openInSystemBrowser(...). Only available on Android and iOS:

import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const close = async () => {
  await InAppBrowser.close();
};

Execute JavaScript in the web view

Execute any JavaScript code in the currently open web view. This method is only available for browsers opened with openInWebView(...) on Android and iOS:

import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const executeScript = async () => {
  const { result } = await InAppBrowser.executeScript({
    script: 'document.title',
  });
  return result;
};

Post a message to the web page

Post a message to the currently open web view. The web page receives the message by listening for the capacitorInAppBrowserMessage window event, see Messaging. This method is only available for browsers opened with openInWebView(...) on Android and iOS:

import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const postMessage = async () => {
  await InAppBrowser.postMessage({
    data: { name: 'Capawesome' },
  });
};

Clear the cache and cookies

Clear the cache or the cookies of the web view, either for all URLs or only for a specific URL. Only available on Android and iOS:

import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const clearCache = async () => {
  await InAppBrowser.clearCache();
};

const clearAllCookies = async () => {
  await InAppBrowser.clearCookies();
};

const clearCookiesForUrl = async () => {
  await InAppBrowser.clearCookies({ url: 'https://capawesome.io' });
};

Listen for browser events

Get notified when the browser is closed, a message is received, a navigation has been completed, a page has been loaded, or the URL has changed:

import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const addListeners = async () => {
  await InAppBrowser.addListener('browserClosed', () => {
    console.log('Browser closed');
  });
  await InAppBrowser.addListener('browserMessageReceived', event => {
    console.log('Message received', event.data);
  });
  await InAppBrowser.addListener('browserNavigationCompleted', event => {
    console.log('Navigation completed', event.url);
  });
  await InAppBrowser.addListener('browserPageLoaded', () => {
    console.log('Browser page loaded');
  });
  await InAppBrowser.addListener('browserUrlChanged', event => {
    console.log('URL changed', event.url);
  });
};

API

clearCache()

clearCache() => Promise<void>

Clear the cache of the web view.

Only available on Android and iOS.

Since: 0.1.0

clearCookies(...)

clearCookies(options?: ClearCookiesOptions | undefined) => Promise<void>

Clear the cookies of the web view.

Provide the url option to clear only the cookies of a specific URL. Otherwise, all cookies are cleared.

Only available on Android and iOS.

Param Type
options ClearCookiesOptions

Since: 0.2.0

close()

close() => Promise<void>

Close the currently open browser.

This closes browsers opened with openInWebView(...) or openInSystemBrowser(...).

Only available on Android and iOS.

Since: 0.1.0

executeScript(...)

executeScript(options: ExecuteScriptOptions) => Promise<ExecuteScriptResult>

Execute a JavaScript script in the currently open web view.

This method is only available for browsers opened with openInWebView(...).

Only available on Android and iOS.

Param Type
options ExecuteScriptOptions

Returns: Promise<ExecuteScriptResult>

Since: 0.1.0

getCookies(...)

getCookies(options: GetCookiesOptions) => Promise<GetCookiesResult>

Get the cookies for a specific URL.

On iOS, only cookies from the shared data store are returned. Cookies from a web view opened with dataStore: 'isolated' are not included.

Only available on Android and iOS.

Param Type
options GetCookiesOptions

Returns: Promise<GetCookiesResult>

Since: 0.1.0

openInExternalBrowser(...)

openInExternalBrowser(options: OpenInExternalBrowserOptions) => Promise<void>

Open a URL in the default browser app of the device.

Param Type
options OpenInExternalBrowserOptions

Since: 0.1.0

openInSystemBrowser(...)

openInSystemBrowser(options: OpenInSystemBrowserOptions) => Promise<void>

Open a URL in the system browser (Custom Tabs on Android, SFSafariViewController on iOS).

Only available on Android and iOS.

Param Type
options OpenInSystemBrowserOptions

Since: 0.1.0

openInWebView(...)

openInWebView(options: OpenInWebViewOptions) => Promise<void>

Open a URL in an embedded web view with a native toolbar.

Only available on Android and iOS.

Param Type
options OpenInWebViewOptions

Since: 0.1.0

postMessage(...)

postMessage(options: PostMessageOptions) => Promise<void>

Post a message to the currently open web view.

The web page receives the message by listening for the capacitorInAppBrowserMessage window event. The message data is available in the detail property of the event.

This method is only available for browsers opened with openInWebView(...).

Only available on Android and iOS.

Param Type
options PostMessageOptions

Since: 0.1.0

show()

show() => Promise<void>

Show the web view if it was opened with visible: false.

This method is only available for browsers opened with openInWebView(...).

Only available on Android and iOS.

Since: 0.1.0

addListener('browserClosed', ...)

addListener(eventName: 'browserClosed', listenerFunc: () => void) => Promise<PluginListenerHandle>

Called when the browser is closed.

Only available on Android and iOS.

Param Type
eventName 'browserClosed'
listenerFunc () => void

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

addListener('browserMessageReceived', ...)

addListener(eventName: 'browserMessageReceived', listenerFunc: (event: BrowserMessageReceivedEvent) => void) => Promise<PluginListenerHandle>

Called when the web page posts a message to the app using the injected window.CapacitorInAppBrowser.postMessage(...) function.

This event is only emitted for browsers opened with openInWebView(...).

Only available on Android and iOS.

Param Type
eventName 'browserMessageReceived'
listenerFunc (event: BrowserMessageReceivedEvent) => void

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

addListener('browserNavigationCompleted', ...)

addListener(eventName: 'browserNavigationCompleted', listenerFunc: (event: BrowserNavigationCompletedEvent) => void) => Promise<PluginListenerHandle>

Called when a page navigation has been completed in the web view.

This event is only emitted for browsers opened with openInWebView(...).

Only available on Android and iOS.

Param Type
eventName 'browserNavigationCompleted'
listenerFunc (event: BrowserNavigationCompletedEvent) => void

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

addListener('browserPageLoaded', ...)

addListener(eventName: 'browserPageLoaded', listenerFunc: () => void) => Promise<PluginListenerHandle>

Called when the initial page of the browser has finished loading.

On Android, this event is only emitted for browsers opened with openInWebView(...).

Only available on Android and iOS.

Param Type
eventName 'browserPageLoaded'
listenerFunc () => void

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

addListener('browserUrlChanged', ...)

addListener(eventName: 'browserUrlChanged', listenerFunc: (event: BrowserUrlChangedEvent) => void) => Promise<PluginListenerHandle>

Called when the current URL of the web view changes, e.g. when the user navigates to a new page, a server redirect occurs, or a single-page application updates the browser history.

This event is also emitted for the initial URL and fires earlier than browserNavigationCompleted.

This event is only emitted for browsers opened with openInWebView(...).

Only available on Android and iOS.

Param Type
eventName 'browserUrlChanged'
listenerFunc (event: BrowserUrlChangedEvent) => void

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.1.0

Interfaces

ClearCookiesOptions

Prop Type Description Since
url string The URL to clear the cookies for. If not provided, all cookies are cleared. 0.2.0

ExecuteScriptResult

Prop Type Description Since
result string | null The result of the script execution serialized as a JSON string. If the script does not return a JSON-serializable value, null is returned. 0.1.0

ExecuteScriptOptions

Prop Type Description Since
script string The JavaScript code to execute in the web view. 0.1.0

GetCookiesResult

Prop Type Description Since
cookies { [key: string]: string; } The cookies for the URL as a map of cookie names to values. 0.1.0

GetCookiesOptions

Prop Type Description Since
url string The URL to get the cookies for. 0.1.0

OpenInExternalBrowserOptions

Prop Type Description Since
url string The URL to open in the external browser. 0.1.0

OpenInSystemBrowserOptions

Prop Type Description Since
android OpenInSystemBrowserAndroidOptions Options that are only applied on Android. Only available on Android. 0.1.0
ios OpenInSystemBrowserIosOptions Options that are only applied on iOS. Only available on iOS. 0.1.0
url string The URL to open in the system browser. 0.1.0

OpenInSystemBrowserAndroidOptions

Prop Type Description Default Since
hideToolbarOnScroll boolean Whether or not the toolbar should be hidden when the user scrolls down and shown when the user scrolls up. false 0.1.0
showTitle boolean Whether or not the title of the web page should be shown in the toolbar. false 0.1.0
toolbarColor string The background color of the toolbar as a hex color code. 0.1.0

OpenInSystemBrowserIosOptions

Prop Type Description Default Since
barCollapsing boolean Whether or not the toolbar should collapse when the user scrolls down. true 0.1.0
dismissButtonStyle DismissButtonStyle The style of the dismiss button in the toolbar. 'done' 0.1.0
readerMode boolean Whether or not the reader mode should be entered if it is available for the web page. false 0.1.0
toolbarColor string The background color of the toolbar as a hex color code. 0.1.0

OpenInWebViewOptions

Prop Type Description Default Since
android OpenInWebViewAndroidOptions Options that are only applied on Android. Only available on Android. 0.1.0
dataStore WebViewDataStore The data store to use for the web view. On Android, this option is ignored. The web view always uses the app-global (shared) data store. Only available on iOS. 'shared' 0.1.0
headers { [key: string]: string; } Additional HTTP headers to send with the initial request. 0.1.0
ios OpenInWebViewIosOptions Options that are only applied on iOS. Only available on iOS. 0.1.0
mediaPlaybackRequiresUserAction boolean Whether or not media playback requires user action. false 0.1.0
toolbar WebViewToolbarOptions Options for the toolbar of the web view. 0.1.0
url string The URL to open in the web view. 0.1.0
userAgent string The custom user agent to use for the web view. 0.1.0
visible boolean Whether or not the web view is presented when opened. If false, the web view loads the URL in the background and stays hidden until show() is called. The browserPageLoaded event is still emitted and close() can be called while the web view is hidden. true 0.1.0

OpenInWebViewAndroidOptions

Prop Type Description Default Since
allowZoom boolean Whether or not the user can zoom the web page. false 0.1.0
hardwareBackButton boolean Whether or not the hardware back button navigates back in the web view's history before closing the web view. If false, the hardware back button closes the web view immediately. true 0.1.0
pauseMediaWhenHidden boolean Whether or not media playback is paused when the app is hidden. true 0.1.0

OpenInWebViewIosOptions

Prop Type Description Default Since
allowsBackForwardNavigationGestures boolean Whether or not horizontal swipe gestures navigate back and forward in the web view's history. false 0.1.0
overscroll boolean Whether or not the web view bounces when scrolled past the edge of the content. true 0.1.0

WebViewToolbarOptions

Prop Type Description Default Since
backgroundColor string The background color of the toolbar as a hex color code. 0.1.0
closeButtonText string The text of the close button in the toolbar. 'Close' 0.1.0
color string The text color of the toolbar as a hex color code. 0.1.0
showNavigationButtons boolean Whether or not the back and forward navigation buttons should be shown in the toolbar. false 0.1.0
showUrl boolean Whether or not the current URL should be displayed in the toolbar instead of the title. false 0.1.0
title string The fixed title to display in the toolbar. If not set, the title of the current web page is displayed. 0.1.0
visible boolean Whether or not the toolbar should be visible. true 0.1.0

PostMessageOptions

Prop Type Description Since
data { [key: string]: unknown; } The message data to post to the web view. Must be a JSON-serializable object. 0.1.0

PluginListenerHandle

Prop Type
remove () => Promise<void>

BrowserMessageReceivedEvent

Prop Type Description Since
data unknown The message data posted by the web page. 0.1.0

BrowserNavigationCompletedEvent

Prop Type Description Since
url string The URL of the page that was navigated to. 0.1.0

BrowserUrlChangedEvent

Prop Type Description Since
url string The new URL of the web view. 0.1.0

Type Aliases

DismissButtonStyle

The style of the dismiss button in the toolbar of the system browser.

  • cancel: A button with the text "Cancel".
  • close: A button with the text "Close".
  • done: A button with the text "Done".

'cancel' | 'close' | 'done'

WebViewDataStore

The data store to use for the web view.

  • isolated: The web view uses a non-persistent data store. Cookies and web storage are discarded when the web view is closed.
  • shared: The web view uses the app-global data store which is shared with other web views.

'isolated' | 'shared'

Messaging

The embedded web view injects a small message bridge into every web page. This allows you to exchange messages between your app and the web page in both directions.

From the web page to the app

The web page can post a message to the app using the injected window.CapacitorInAppBrowser.postMessage(...) function:

window.CapacitorInAppBrowser.postMessage({ name: 'Capawesome' });

The app receives the message via the browserMessageReceived event.

From the app to the web page

The app can post a message to the web page using the postMessage(...) method. The web page receives the message by listening for the capacitorInAppBrowserMessage window event:

window.addEventListener('capacitorInAppBrowserMessage', event => {
  console.log('Message received', event.detail);
});

Platform Behavior

The three browser modes behave differently on each platform. Keep the following differences in mind:

  • System browser: Tracking the visited URLs is not possible by design. If you need the browserNavigationCompleted or browserUrlChanged event, use the openInWebView(...) method instead. On Android, the browserPageLoaded event is not emitted for the system browser and the browserClosed event is emitted when the user returns to the app.
  • Embedded web view: The web view always uses the app-global (shared) data store on Android. The dataStore option is only supported on iOS. On iOS, hiding the toolbar removes the close button, so the browser can then only be closed using the close(...) method.
  • External browser: The browser is opened in a separate app. For this reason, no events are emitted and the close(...) method has no effect.

FAQ

How is this plugin different from other similar plugins?

It covers three browsing modes in one fully typed API — the external browser, the system browser (Custom Tabs on Android, SFSafariViewController on iOS), and an embedded web view with a themed native toolbar, JavaScript execution, two-way messaging, navigation events, and session control. Camera and microphone requests from web pages are forwarded to the app, and you can even load a URL hidden in the background and present it once it's ready. If you only need to open a link, the external mode is a simple one-liner; if you need to embed, theme, and communicate with web content, this plugin is designed for exactly that.

What is the difference between the external browser, the system browser and the embedded web view?

The openInExternalBrowser(...) method opens the URL in the default browser app of the device, so no events are emitted and the close() method has no effect. The openInSystemBrowser(...) method presents the system browser (Custom Tabs on Android, SFSafariViewController on iOS) inside your app with a customizable toolbar. The openInWebView(...) method opens an embedded web view with a native toolbar and offers the most control, including JavaScript execution, messaging, and navigation events. See Platform Behavior for the differences between the modes.

How can I track which URLs the user visits?

Tracking the visited URLs is only possible in the embedded web view. Open the URL with openInWebView(...) and listen for the browserUrlChanged or browserNavigationCompleted event. In the system browser, tracking the visited URLs is not possible by design, and in the external browser no events are emitted at all.

How can I exchange data between my app and the opened web page?

The embedded web view injects a small message bridge into every web page. The web page can post messages to the app using the injected window.CapacitorInAppBrowser.postMessage(...) function, which the app receives via the browserMessageReceived event. The app can post messages to the web page using the postMessage(...) method, which the web page receives via the capacitorInAppBrowserMessage window event. See Messaging for more details.

Can web pages access the camera or microphone?

Yes, camera and microphone permission requests from web pages opened in the embedded web view are forwarded to the app. On Android, the corresponding permissions must be declared in your AndroidManifest.xml and granted before a web page requests access. On iOS, the NSCameraUsageDescription and NSMicrophoneUsageDescription keys must be added to your Info.plist file. See Installation for details.

Can I load a URL in the background before showing it?

Yes, open the URL with openInWebView(...) and set the visible option to false. The web view then loads the URL in the background and stays hidden until you call the show() method. The browserPageLoaded event is still emitted and close() can be called while the web view is hidden.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

  • App Launcher: Check if an app can be opened and open it.
  • OAuth: Communicate with OAuth 2.0 and OpenID Connect providers.
  • System WebView: Detect an outdated Android System WebView and guide users to update it.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

Breaking Changes

See BREAKING.md.

License

See LICENSE.