@capgo/capacitor-inappbrowser

v8.26.2

Published

4 days ago

Capacitor plugin in app browser

0High
0Medium
0Low

riderx

torichancapgo

capacitor plugin browser native

@capgo/capacitor-inappbrowser

Open web content inside your Capacitor app with a full-featured in-app browser: custom toolbars, two-way messaging, JavaScript injection, navigation events and native layering behind your UI.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-inappbrowser in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-inappbrowser to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

Two browser modes: open() uses SFSafariViewController on iOS and Chrome Custom Tabs on Android, openWebView() opens a WebView with your own toolbar, title, colors and buttons.
Two-way messaging: postMessage() and the messageFromWebview event, plus executeScript() to run code in the page.
Navigation events: urlChangeEvent, browserPageLoaded, pageLoadError, closeEvent, downloads and popups.
Layout control: updateDimensions(), fullscreen, safe-area margins, hide(), show() and sendToBack() to place the browser behind your Ionic UI.
Session data: getCookies(), clearCookies(), clearCache() and clearAllBrowsingData().
OAuth: openSecureWindow() runs an auth flow with ASWebAuthenticationSession on iOS and Custom Tabs on Android, and a popup on web.
Platforms: iOS and Android. On web only openSecureWindow() and a few helpers do real work.

Why InAppBrowser?

The official Capacitor Browser plugin has strict security limitations that prevent advanced features. InAppBrowser removes these restrictions, enabling:

Two-way communication between your app and the browser
JavaScript injection for dynamic content manipulation
Camera and microphone access within the browser context
URL change monitoring for navigation tracking
Custom toolbars and UI for branded experiences
Native browser layering behind Ionic or Capacitor UI with input forwarding
Partial-screen WebViews with click-through areas outside the browser frame
Cookie, cache, and full browsing-data controls for private or isolated sessions
Native proxy, download, and popup handling for advanced embedded web apps

Perfect for OAuth flows, embedded web apps, checkout screens, browser-backed payment flows, video calls, support portals, and apps that need native UI around live web content.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/inappbrowser/

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ | | v5.*.* | v5.*.* | ❌ |

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

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

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-inappbrowser` 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 @capgo/capacitor-inappbrowser
npx cap sync

Usage

import { InAppBrowser } from '@capgo/capacitor-inappbrowser';

InAppBrowser.open({ url: 'YOUR_URL' });

Common use cases

Show Ionic UI over a live browser page

Use toBack when the native browser should stay visible behind your Ionic or Capacitor UI. This is useful for checkout overlays, payment confirmation panels, guided browser flows, or any flow where your app owns the controls while the web page remains loaded behind it.

import { InAppBrowser } from '@capgo/capacitor-inappbrowser';

const { id } = await InAppBrowser.openWebView({
  url: 'https://example.com/checkout',
  toBack: true,
  transparentBackground: true,
});

// If your overlay needs to interact with the page behind it, forward the gesture.
await InAppBrowser.dispatchInputEvent({
  id,
  type: 'click',
  x: 160,
  y: 420,
});

// Bring the browser back above the app when the native overlay is done.
await InAppBrowser.bringToFront({ id });

Make the app background transparent wherever the browser should be visible. dispatchInputEvent() supports click, touch, and scroll forwarding; coordinates are relative to the browser viewport.

Build a partial-screen browser or bottom sheet

Use height, width, x, and y for picture-in-picture views, browser sheets, or layouts where the user should keep interacting with the Ionic app around the browser. When the WebView does not cover the full screen, touches outside the browser frame pass through to the underlying Capacitor WebView on Android and iOS.

const bottomGap = 200;

const { id } = await InAppBrowser.openWebView({
  url: 'https://example.com/offers',
  height: window.innerHeight - bottomGap,
  y: 0,
});

Use updateDimensions() to resize the browser while keeping the same page state, for example when expanding a mini browser into a larger sheet.

Keep checkout, auth, or support sessions private

Use persistWebViewData: false when a WebView must avoid persistent cookies, cache, local storage, IndexedDB, and other website data where the platform supports it. Use clearAllBrowsingData() when the app needs to wipe InAppBrowser-managed browsing data without touching the Capacitor/Ionic host WebView.

const { id } = await InAppBrowser.openWebView({
  url: 'https://example.com/login',
  persistWebViewData: false,
});

// Later, after logout or account switching:
await InAppBrowser.clearAllBrowsingData();

Share host WebView cookies for SSO (iOS 17+)

On iOS 17+, InAppBrowser isolates cookies from the Capacitor host WebView by default. If your app completes OIDC/SSO login in the main WebView and partner sites opened in the in-app browser need that IdP session cookie, set useSharedDataStore: true:

const { id } = await InAppBrowser.openWebView({
  url: 'https://partner.example/sso',
  useSharedDataStore: true,
});

Android already shares cookies process-wide, so this flag is a no-op there. Do not enable it unless you need host session sharing, clearing cookies/cache for that webview can affect the host WebView on iOS.

Keep multiple browser instances ready

Use hidden, hide(), and show() when you need to preload or preserve several WebViews without keeping them on screen. This keeps browser state available while the native modal is dismissed so it does not block touches in the app.

const first = await InAppBrowser.openWebView({ url: 'https://example.com/a', hidden: true });
const second = await InAppBrowser.openWebView({ url: 'https://example.com/b', hidden: true });

await InAppBrowser.show({ id: first.id });
await InAppBrowser.hide({ id: first.id });
await InAppBrowser.show({ id: second.id });

Listen to console output from the managed page

See consoleMessage and captureConsoleLogs.

import { InAppBrowser } from '@capgo/capacitor-inappbrowser';

const listener = await InAppBrowser.addListener('consoleMessage', (event) => {
  console.log(event.level, event.message);
});

const { id } = await InAppBrowser.openWebView({
  url: 'https://example.com/checkout',
  captureConsoleLogs: true,
});

await listener.remove();
await InAppBrowser.close({ id });

Hide from the native close button and brand the toolbar title

Use closeAction: CloseAction.HIDE when the toolbar close button should hide the WebView instead of destroying it. Listen to hideEvent if your app needs to update Ionic state, then call show() later to bring the same browser session back. Set screenshotOnHide to receive one last visible-page screenshot in that event. On iOS, Apple's iPhone Mirroring app (device locked) can return a correctly sized but fully transparent PNG from that capture; use a normal unlocked device when validating screenshots.

import { CloseAction, InAppBrowser } from '@capgo/capacitor-inappbrowser';

await InAppBrowser.addListener('hideEvent', ({ id, url, screenshot }) => {
  console.log('Browser hidden', id, url, screenshot?.dataUrl);
});

const { id } = await InAppBrowser.openWebView({
  url: 'https://example.com/checkout',
  title: 'Secure checkout',
  closeAction: CloseAction.HIDE,
  screenshotOnHide: true,
  titleFontFamily: 'Inter',
  titleIcon: {
    ios: { iconType: 'sf-symbol', icon: 'lock.fill' },
    android: { iconType: 'vector', icon: 'ic_lock', width: 20, height: 20 },
  },
});

// Later, after the toolbar close button hides it:
await InAppBrowser.show({ id });

For iOS, titleFontFamily must match a registered font family name and titleIcon can use either an SF Symbol or bundled asset. For Android, titleFontFamily first checks res/font and then falls back to a system font family; titleIcon can use a vector drawable or bundled SVG asset.

Embed advanced web app flows

Use proxy rules and handleDownloads for web apps that need request control, file uploads, downloads, or controlled popup behavior inside the managed browser. Typical examples include document portals, support desks, payment pages, Google Pay flows on Android, and apps that need to keep _blank links inside the same managed WebView.

Customize Chrome Custom Tab Appearance (Android)

The open() method launches a Chrome Custom Tab on Android. You can customize its appearance to blend with your app:

import { InAppBrowser } from '@capgo/capacitor-inappbrowser';

InAppBrowser.open({
  url: 'https://example.com',
  toolbarColor: '#1A1A2E', // Match your app's theme
  showTitle: true, // Show page title instead of raw URL
  showArrow: true, // Back arrow instead of X close icon
  urlBarHidingEnabled: true, // Auto-hide URL bar on scroll
  disableShare: true, // Remove share from overflow menu
  disableBookmark: true, // Hide bookmark icon (undocumented, may break)
  disableDownload: true, // Hide download icon (undocumented, may break)
});

All CCT options are Android-only and safely ignored on iOS. See OpenOptions for full documentation.

Open WebView with Custom Dimensions

By default, the WebView fills the available screen and retains its configured toolbar. You can set custom dimensions to control the size and position:

import { InAppBrowser } from '@capgo/capacitor-inappbrowser';

// Open with custom dimensions (400x600 at position 50,100)
const { id } = await InAppBrowser.openWebView({
  url: 'YOUR_URL',
  width: 400,
  height: 600,
  x: 50,
  y: 100,
});

// Update dimensions at runtime
InAppBrowser.updateDimensions({
  id, // Optional, if omitted targets the active webview
  width: 500,
  height: 700,
  x: 100,
  y: 150,
});

Touch Passthrough: When custom dimensions are set (not fullscreen), touches outside the webview bounds will pass through to the underlying Capacitor webview, allowing the user to interact with your app in the exposed areas. This enables picture-in-picture style experiences where the InAppBrowser floats above your content.

Open WebView with Safe Margin

To create a webView with a 20px bottom margin (safe margin area outside the browser):

import { InAppBrowser } from '@capgo/capacitor-inappbrowser';

InAppBrowser.openWebView({
  url: 'YOUR_URL',
  enabledSafeBottomMargin: true,
});

Web platform is not supported. Use window.open instead.

Fullscreen at launch and during a session

Set fullscreen: true to present a native WebView in fullscreen from its first visible frame:

import { InAppBrowser, ToolBarType } from '@capgo/capacitor-inappbrowser';

const listener = await InAppBrowser.addListener('fullscreenChange', ({ id, enabled }) => {
  console.log('Fullscreen changed', id, enabled);
});

const { id } = await InAppBrowser.openWebView({
  url: 'https://example.com',
  toolbarType: ToolBarType.NAVIGATION,
  fullscreen: true,
});

await InAppBrowser.setFullscreen({ id, enabled: false });
await InAppBrowser.setFullscreen({ id, enabled: true });
const { enabled } = await InAppBrowser.getFullscreen({ id });

// When the host no longer needs updates:
await listener.remove();

Fullscreen hides native navigation and system bars. A native exit button stays above the page at the top-right safe-area inset. Android Back exits fullscreen before navigating page history. Exiting restores the configured toolbar and safe-area settings. Entry and exit keep the same WebView, including its JavaScript state, cookies, and history.

The opening option defaults to false. It also works with isPresentAfterPageLoad: true and hidden: true. An initially hidden WebView applies fullscreen when first shown; until then, getFullscreen() reports false and the host's system bars stay unchanged. Calling setFullscreen({ id, enabled: false }) cancels that pending startup request.

Backgrounding, hiding, closing, cross-origin navigation, and renderer termination exit fullscreen through native cleanup. Showing or resuming the WebView afterward does not enter fullscreen again. The host receives a fullscreenChange event for each applied change, including native exit controls. Register the listener before opening to observe initial entry.

These APIs control the browser's presentation independently of HTML/video fullscreen. They support full-size, frontmost openWebView presentations on iOS and Android. Runtime entry into a hidden WebView, custom dimensions, behind-host presentations, and missing target IDs reject. Web usage is unsupported. Permission prompts are the host application's responsibility.

The example app's Fullscreen section includes launch options and an interactive page for runtime entry, exit, hide/show, history, form, cookie, and counter checks.

Extend content behind the status bar

To extend content behind the status bar, set enabledSafeTopMargin to false:

import { InAppBrowser } from '@capgo/capacitor-inappbrowser';

InAppBrowser.openWebView({
  url: 'YOUR_URL',
  enabledSafeTopMargin: false, // Disables safe area at top, allows full screen
});

This option works independently of the toolbar type:

iOS: The webview extends behind the status bar, providing true edge-to-edge content
Android: The top margin is disabled, allowing content to fill the entire screen

This setting controls the content inset. Use fullscreen to hide native navigation and system bars as well.

Proxy examples

[!IMPORTANT] Proxy handling changed substantially in 8.6.0. If you already rely on the older proxy flow, treat this as a breaking migration and retest your handlers before shipping. Existing proxy handlers are not assumed to be drop-in compatible just because the API name stayed the same.
Native-first matching now uses outboundProxyRules and inboundProxyRules.
JavaScript proxy handlers now receive a phase (outbound or inbound).
If you respond manually with handleProxyRequest(...), pass the same phase back to native.
Late replies without the original phase can now be ignored instead of mutating the wrong request stage.
proxyRequests: true and proxyRequests: "<regex>" remain legacy compatibility modes. Do not mix legacy mode with the new rule-based flow without retesting.
Existing proxy listeners that only key on URL/method and do not preserve phase are not drop-in compatible with the new flow.

[!WARNING] iOS update: HTTP and HTTPS proxy interception is no longer in the default build. Earlier 8.x releases called method_exchangeImplementations so WKWebView could hand http and https to the proxy scheme handler. App Review guideline 2.5.2 scans the shipped binary for that call and can reject the app even when you never enable proxy. Upgrading this plugin leaves the call out. proxyRequests, outboundProxyRules, and inboundProxyRules will not intercept HTTP or HTTPS until you opt in.
If you still need that interception, add this to capacitor.config.ts:

plugins: {
  CapgoInAppBrowser: {
    httpProxySwizzle: true,
  },
},

Then run npx cap sync. The sync hook includes HttpProxySchemeSwizzle.swift and excludes the stub. That build calls method_exchangeImplementations so WKWebView can hand http and https to the proxy scheme handler. proxyRequests, outboundProxyRules, and inboundProxyRules intercept those requests again. Leaving the key unset, or setting it to false, keeps the stub and leaves the call out of the binary. Android proxy handling does not use this switch. Run npx cap sync again after you change the flag. When a build without the swizzle tries to register http or https, WKWebView.enableCustomSchemeHandling logs the reason once.

Enabling the swizzle can make App Review harder. Guideline 2.5.2 scans the shipped binary for method_exchangeImplementations. If the app needs HTTP or HTTPS interception, say so in the review notes and explain why. Apple may approve that use case by case. The scanner may also never flag the binary.

Block one request natively

Use a native rule when you just want to stop a request without round-tripping through JavaScript:

import { InAppBrowser } from '@capgo/capacitor-inappbrowser';

await InAppBrowser.openWebView({
  url: 'https://example.com',
  outboundProxyRules: [
    {
      urlRegex: '^https://www\\.google-analytics\\.com/.*',
      action: 'cancel',
    },
  ],
});

Stub one script from JavaScript

Use delegateToJs when you want native matching, but still want JavaScript to replace the response:

import { InAppBrowser, addProxyHandler } from '@capgo/capacitor-inappbrowser';

const proxyHandle = await addProxyHandler(async (request) => {
  if (request.phase === 'inbound' && request.url.includes('connect.facebook.net')) {
    return new Response('window.FB = { init: () => {}, login: () => {}, getLoginStatus: () => {} };', {
      status: 200,
      headers: {
        'Content-Type': 'application/javascript; charset=utf-8',
      },
    });
  }

  return null;
});

await InAppBrowser.openWebView({
  url: 'https://www.grailed.com/users/sign_up',
  inboundProxyRules: [
    {
      urlRegex: '^https://connect\\.facebook\\.net/.*',
      action: 'delegateToJs',
    },
  ],
});

// Later, when you are done:
await proxyHandle.remove();

Rewrite an outbound API request in JavaScript

When a request must be modified before it leaves the webview, return a request override:

import { InAppBrowser, addProxyHandler } from '@capgo/capacitor-inappbrowser';

const proxyHandle = await addProxyHandler(async (request) => {
  if (request.phase === 'outbound' && request.url.includes('/api/private')) {
    return {
      request: {
        url: request.url,
        headers: {
          ...request.headers,
          Authorization: 'Bearer MY_TOKEN',
          'X-Proxy-Debug': 'enabled',
        },
      },
    };
  }

  return null;
});

await InAppBrowser.openWebView({
  url: 'https://example.com/dashboard',
  outboundProxyRules: [
    {
      urlRegex: '^https://example\\.com/api/private.*',
      action: 'delegateToJs',
    },
  ],
});

// Later, when you are done:
await proxyHandle.remove();

Test app and code:

https://github.com/Cap-go/demo-app/blob/main/src/views/plugins/Web.vue

Camera usage

Android

Add the following to your AndroidManifest.xml file:

    <uses-permission android:name="android.permission.CAMERA" />
		<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
		<uses-permission android:name="android.permission.RECORD_AUDIO"/>

Then the permission will be asked when the camera is used.

iOS

Add the following to your Info.plist file:

<key>NSCameraUsageDescription</key>
<string>We need access to the camera to record audio.</string>

Microphone usage

Android

Add the following to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

Then the permission will be asked when the microphone is used.

iOS

Add the following to your Info.plist file:

<key>NSMicrophoneUsageDescription</key>
<string>We need access to the microphone to record audio.</string>

Location usage

Android

Add the following to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Then the permission will be asked when location is requested by a website in the webview.

iOS

Add the following to your Info.plist file:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need access to your location to provide location-based services.</string>

Two way communication

With this plugin you can send events from the main app to the inappbrowser and vice versa.

The data is sent as a JSON object, so no functions or other non-JSON-serializable types are allowed.

Main app to inappbrowser, detail object is mendatory

const { id } = await InAppBrowser.openWebView({ url: 'YOUR_URL' });
InAppBrowser.postMessage({ id, detail: { message: 'myMessage' } });
// Or broadcast to all open webviews
InAppBrowser.postMessage({ detail: { message: 'broadcast' } });

Receive event from native in the inappbrowser

window.addEventListener('messageFromNative', (event) => {
  console.log(event);
});

Send event from inappbrowser to main app, detail object is mendatory

window.mobileApp.postMessage({ detail: { message: 'myMessage' } });

Receive event from inappbrowser in the main app

InAppBrowser.addListener('messageFromWebview', (event) => {
  console.log(event.id, event.detail);
});

Close inappbrowser from inappbrowser itself

window.mobileApp.close();

Google Pay (Android)

To enable Google Pay inside the in-app browser on Android you must do all three of the following:

1. Enable the option when opening the browser

Pass enableGooglePaySupport: true in your openWebView call:

InAppBrowser.openWebView({
  url: 'https://your-checkout-page.example.com',
  enableGooglePaySupport: true,
});

2. Add Payment Request intent queries to your `AndroidManifest.xml`

Android 11+ enforces Package Visibility. Without these entries the WebView cannot discover Google Pay and the payment sheet will never appear.

Add the following inside the <manifest> tag of your app's AndroidManifest.xml (typically android/app/src/main/AndroidManifest.xml):

<queries>
  <!-- Required for Google Pay / Payment Request API in WebView -->
  <intent>
    <action android:name="org.chromium.intent.action.PAY" />
  </intent>
  <intent>
    <action android:name="org.chromium.intent.action.IS_READY_TO_PAY" />
  </intent>
  <intent>
    <action android:name="org.chromium.intent.action.UPDATE_PAYMENT_DETAILS" />
  </intent>
</queries>

3. Require WebView 120 or later

The W3C Payment Request API (used by Google Pay) requires Android WebView 120+. Devices running an older WebView version will not be able to complete Google Pay transactions. Most modern Android devices already meet this requirement.

openSecureWindow (OAuth)

Opens a secured window for OAuth2 authentication.

Web

On the redirected page, send the final URL back to the app with a BroadcastChannel, then close the window:

<html>
<head></head>
<body>
<script>
  const searchParams = new URLSearchParams(location.search)
  if (searchParams.has("code")) {
    new BroadcastChannel("my-channel-name").postMessage(location.href);
    window.close();
  }
</script>
</body>
</html>

Mobile

Use a redirect URI that opens the app, for example myapp://oauth_callback/.

<key>CFBundleURLTypes</key>
<array>
   <dict>
      <key>CFBundleURLSchemes</key>
      <array>
         <string>myapp</string>
      </array>
   </dict>
</array>

And in AndroidManifest.xml:

<activity>
   <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:host="oauth_callback" android:scheme="myapp" />
   </intent-filter>
</activity>

Bundled local assets

openWebView() can load HTML, JavaScript, CSS, and other files from the app public/ folder without starting a local HTTP server. Pass a relative path and the plugin resolves it to the Capacitor local URL for the current platform.

import { InAppBrowser } from '@capgo/capacitor-inappbrowser';

await InAppBrowser.openWebView({
  url: '/index.html',
});

iOS resolves to capacitor://localhost/... and serves files from the packaged public/ directory.
Android resolves to https://localhost/... and intercepts requests with WebViewAssetLoader, matching Capacitor's main WebView behavior.
Remote http:// and https:// URLs are unchanged.

open() uses the system browser (Safari / Custom Tabs) and still requires a real remote URL.

API

goBack(...)

goBack(options?: { id?: string | undefined; } | undefined) => Promise<{ canGoBack: boolean; }>

Navigates back in the WebView's history if possible

| Param | Type | | ------------- | ----------------------------- | | options | { id?: string; } |

Returns: Promise<{ canGoBack: boolean; }>

Since: 7.21.0

open(...)

open(options: OpenOptions) => Promise<any>

Open url in a new window fullscreen, on android it use chrome custom tabs, on ios it use SFSafariViewController On web, opens the URL in a new tab via window.open and rejects with Popup blocked when the browser blocks it.

| Param | Type | | ------------- | --------------------------------------------------- | | options | OpenOptions |

Returns: Promise<any>

Since: 0.1.0

clearCookies(...)

clearCookies(options: ClearCookieOptions) => Promise<any>

Clear cookies of url When id is omitted, applies to all open webviews.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | ClearCookieOptions |

Returns: Promise<any>

Since: 0.5.0

clearAllCookies(...)

clearAllCookies(options?: { id?: string | undefined; } | undefined) => Promise<any>

Clear all cookies When id is omitted, applies to all open webviews.

| Param | Type | | ------------- | ----------------------------- | | options | { id?: string; } |

Returns: Promise<any>

Since: 6.5.0

clearCache(...)

clearCache(options?: { id?: string | undefined; } | undefined) => Promise<any>

Clear cache When id is omitted, applies to all open webviews.

| Param | Type | | ------------- | ----------------------------- | | options | { id?: string; } |

Returns: Promise<any>

Since: 6.5.0

clearAllBrowsingData()

clearAllBrowsingData() => Promise<any>

Clear all browsing data from InAppBrowser-managed webviews and the plugin-owned data store.

This removes cookies, disk cache, memory cache, local storage, session storage, IndexedDB, WebSQL where supported, form data, and HTTP auth data for InAppBrowser only.

It does not clear the Capacitor/Ionic host WebView stores. On iOS 17+, InAppBrowser uses a dedicated persistent WKWebsiteDataStore so host and browser data stay isolated (unless useSharedDataStore: true was set on openWebView). On Android, process-global CookieManager / WebStorage are shared with the host WebView and are not wiped by this method; open managed WebViews still clear per-view cache/history and page storage.

Returns: Promise<any>

Since: 8.6.36

getCookies(...)

getCookies(options: GetCookieOptions) => Promise<Record<string, string>>

Get cookies for a specific URL.

| Param | Type | Description | | ------------- | ------------------------------------------------------------- | -------------------------------------------------- | | options | GetCookieOptions | The options, including the URL to get cookies for. |

Returns: Promise<Record<string, string>>

close(...)

close(options?: CloseWebviewOptions | undefined) => Promise<any>

Close the webview. When id is omitted, closes the active webview.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | CloseWebviewOptions |

Returns: Promise<any>

hide(...)

hide(options?: { id?: string | undefined; } | undefined) => Promise<void>

Hide the webview without closing it. Use show() to bring it back. When id is omitted, targets the active webview.

| Param | Type | | ------------- | ----------------------------- | | options | { id?: string; } |

Since: 8.0.8

show(...)

show(options?: { id?: string | undefined; } | undefined) => Promise<void>

Show a previously hidden webview. When id is omitted, targets the active webview.

| Param | Type | | ------------- | ----------------------------- | | options | { id?: string; } |

Since: 8.0.8

sendToBack(...)

sendToBack(options?: LayerOptions | undefined) => Promise<void>

Moves the native browser behind the Capacitor host WebView. Use dispatchInputEvent() to forward overlay gestures to the browser while it is behind the app UI.

| Param | Type | | ------------- | ----------------------------------------------------- | | options | LayerOptions |

bringToFront(...)

bringToFront(options?: BringToFrontOptions | undefined) => Promise<void>

Moves a browser that was behind the host WebView back to the front. On iOS, set isAnimated to false to skip the presentation animation. When id is omitted, targets the active webview.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | BringToFrontOptions |

dispatchInputEvent(...)

dispatchInputEvent(options: DispatchInputEventOptions) => Promise<void>

Dispatches a click, touch, or scroll event to a managed browser. Coordinates are relative to the browser viewport in CSS pixels.

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | DispatchInputEventOptions |

openWebView(...)

openWebView(options: OpenWebViewOptions) => Promise<{ id: string; }>

Open url in a new webview with toolbars, and enhanced capabilities, like camera access, file access, listen events, inject javascript, bi directional communication, etc.

JavaScript Interface: When you open a webview with this method, a JavaScript interface is automatically injected that provides:

window.mobileApp.close(): Closes the webview from JavaScript
window.mobileApp.postMessage({detail: {message: "myMessage"}}): Sends a message from the webview to the app, detail object is the data you want to send to the webview
window.mobileApp.takeScreenshot() when allowScreenshotsFromWebPage is true

Promise timing differs by platform when isPresentAfterPageLoad is used. Android resolves with { id } after the dialog is ready to control, while iOS resolves with { id } immediately after creating the native webview.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | OpenWebViewOptions |

Returns: Promise<{ id: string; }>

Since: 0.1.0

executeScript(...)

executeScript(options: { code: string; id?: string; }) => Promise<void>

Injects JavaScript code into the InAppBrowser window. When id is omitted, executes in all open webviews.

| Param | Type | | ------------- | ------------------------------------------- | | options | { code: string; id?: string; } |

postMessage(...)

postMessage(options: { detail: Record<string, any>; id?: string; }) => Promise<void>

Sends an event to the webview(inappbrowser). you can listen to this event in the inappbrowser JS with window.addEventListener("messageFromNative", listenerFunc: (event: Record<string, any>) => void) detail is the data you want to send to the webview, it's a requirement of Capacitor we cannot send direct objects Your object has to be serializable to JSON, so no functions or other non-JSON-serializable types are allowed. When id is omitted, broadcasts to all open webviews.

| Param | Type | | ------------- | -------------------------------------------------------------------------------------- | | options | { detail: Record<string, any>; id?: string; } |

takeScreenshot(...)

takeScreenshot(options?: { id?: string | undefined; } | undefined) => Promise<ScreenshotResult>

Captures the current webview viewport as a PNG screenshot. When id is omitted, targets the active webview.

On iOS, when testing through Apple's iPhone Mirroring app with the physical device locked, the snapshot can succeed with the correct dimensions but a fully transparent PNG. Capture works as expected on a normal unlocked device.

| Param | Type | | ------------- | ----------------------------- | | options | { id?: string; } |

Returns: Promise<ScreenshotResult>

setUrl(...)

setUrl(options: { url: string; id?: string; }) => Promise<any>

Sets the URL of the webview. When id is omitted, targets the active webview.

| Param | Type | | ------------- | ------------------------------------------ | | options | { url: string; id?: string; } |

Returns: Promise<any>

addListener('urlChangeEvent', ...)

addListener(eventName: 'urlChangeEvent', listenerFunc: UrlChangeListener) => Promise<PluginListenerHandle>

Listen for url change, only for openWebView

| Param | Type | | ------------------ | --------------------------------------------------------------- | | eventName | 'urlChangeEvent' | | listenerFunc | UrlChangeListener |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('fullscreenChange', ...)

addListener(eventName: 'fullscreenChange', listenerFunc: (event: FullscreenChangeEvent) => void) => Promise<PluginListenerHandle>

Listen for applied fullscreen changes, including startup entry, the native exit button, Android Back, and native lifecycle cleanup. Register before opening to observe startup entry. Repeated requests for the current state do not emit duplicate events. This event describes host-controlled fullscreen, not HTML/video fullscreen.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------- | | eventName | 'fullscreenChange' | | listenerFunc | (event: FullscreenChangeEvent) => void |

Returns: Promise<PluginListenerHandle>

addListener('buttonNearDoneClick', ...)

addListener(eventName: 'buttonNearDoneClick', listenerFunc: ButtonNearListener) => Promise<PluginListenerHandle>

Listen for buttonNearDone clicks.

The event payload contains the webview id.

| Param | Type | | ------------------ | ----------------------------------------------------------------- | | eventName | 'buttonNearDoneClick' | | listenerFunc | ButtonNearListener |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('closeEvent', ...)

addListener(eventName: 'closeEvent', listenerFunc: UrlChangeListener) => Promise<PluginListenerHandle>

Listen for close click only for openWebView

| Param | Type | | ------------------ | --------------------------------------------------------------- | | eventName | 'closeEvent' | | listenerFunc | UrlChangeListener |

Returns: Promise<PluginListenerHandle>

Since: 0.4.0

addListener('hideEvent', ...)

addListener(eventName: 'hideEvent', listenerFunc: HideListener) => Promise<PluginListenerHandle>

Listen for webviews hidden by the toolbar close button when closeAction is CloseAction.HIDE.

| Param | Type | | ------------------ | ----------------------------------------------------- | | eventName | 'hideEvent' | | listenerFunc | HideListener |

Returns: Promise<PluginListenerHandle>

Since: 8.7.7

addListener('confirmBtnClicked', ...)

addListener(eventName: 'confirmBtnClicked', listenerFunc: ConfirmBtnListener) => Promise<PluginListenerHandle>

Will be triggered when user clicks on confirm button when disclaimer is required, works with openWebView shareDisclaimer and closeModal

| Param | Type | | ------------------ | ----------------------------------------------------------------- | | eventName | 'confirmBtnClicked' | | listenerFunc | ConfirmBtnListener |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('messageFromWebview', ...)

addListener(eventName: 'messageFromWebview', listenerFunc: (event: { id?: string; detail?: Record<string, any>; rawMessage?: string; }) => void) => Promise<PluginListenerHandle>

Will be triggered when event is sent from webview(inappbrowser), to send an event to the main app use window.mobileApp.postMessage({ "detail": { "message": "myMessage" } }) detail is the data you want to send to the main app, it's a requirement of Capacitor we cannot send direct objects Your object has to be serializable to JSON, no functions or other non-JSON-serializable types are allowed.

This method is inject at runtime in the webview

| Param | Type | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- | | eventName | 'messageFromWebview' | | listenerFunc | (event: { id?: string; detail?: Record<string, any>; rawMessage?: string; }) => void |

Returns: Promise<PluginListenerHandle>

addListener('screenshotTaken', ...)

addListener(eventName: 'screenshotTaken', listenerFunc: (event: ScreenshotResult & { id?: string; }) => void) => Promise<PluginListenerHandle>

Will be triggered whenever a screenshot is captured from the plugin API, the native screenshot button, or the injected JavaScript bridge.

| Param | Type | | ------------------ | ---------------------------------------------------------------------------------------------------- | | eventName | 'screenshotTaken' | | listenerFunc | (event: ScreenshotResult & { id?: string; }) => void |

Returns: Promise<PluginListenerHandle>

addListener('browserPageLoaded', ...)

addListener(eventName: 'browserPageLoaded', listenerFunc: (event: { id?: string; }) => void) => Promise<PluginListenerHandle>

Will be triggered when page is loaded

| Param | Type | | ------------------ | ------------------------------------------------- | | eventName | 'browserPageLoaded' | | listenerFunc | (event: { id?: string; }) => void |

Returns: Promise<PluginListenerHandle>

addListener('browserPageLoadStart', ...)

addListener(eventName: 'browserPageLoadStart', listenerFunc: (event: { id?: string; }) => void) => Promise<PluginListenerHandle>

Will be triggered when a main-frame page load starts (link navigation, reload, etc.).

| Param | Type | | ------------------ | ------------------------------------------------- | | eventName | 'browserPageLoadStart' | | listenerFunc | (event: { id?: string; }) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.11.0

addListener('browserPageLoadProgress', ...)

addListener(eventName: 'browserPageLoadProgress', listenerFunc: (event: { id?: string; progress: number; }) => void) => Promise<PluginListenerHandle>

Will be triggered as a main-frame page load progresses. progress is a value from 0 to 1.

| Param | Type | | ------------------ | ------------------------------------------------------------------- | | eventName | 'browserPageLoadProgress' | | listenerFunc | (event: { id?: string; progress: number; }) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.11.0

addListener('pageLoadError', ...)

addListener(eventName: 'pageLoadError', listenerFunc: (event: { id?: string; }) => void) => Promise<PluginListenerHandle>

Will be triggered when page load error

| Param | Type | | ------------------ | ------------------------------------------------- | | eventName | 'pageLoadError' | | listenerFunc | (event: { id?: string; }) => void |

Returns: Promise<PluginListenerHandle>

addListener('customSchemeIntercepted', ...)

addListener(eventName: 'customSchemeIntercepted', listenerFunc: CustomSchemeInterceptedListener) => Promise<PluginListenerHandle>

Will be triggered when the webview intercepts a non-standard custom scheme and hands it to the operating system.

Standard OS-handled schemes such as tel:, mailto:, and sms: are excluded. On iOS, opened is reported asynchronously after UIApplication.open completes.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------- | | eventName | 'customSchemeIntercepted' | | listenerFunc | CustomSchemeInterceptedListener |

Returns: Promise<PluginListenerHandle>

Since: 8.6.7

addListener('downloadCompleted', ...)

addListener(eventName: 'downloadCompleted', listenerFunc: (event: DownloadCompletedEvent) => void) => Promise<PluginListenerHandle>

Will be triggered after native download handling saves a file locally. Enable this with handleDownloads: true when opening the webview.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------------------- | | eventName | 'downloadCompleted' | | listenerFunc | (event: DownloadCompletedEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.6.0

addListener('downloadFailed', ...)

addListener(eventName: 'downloadFailed', listenerFunc: (event: DownloadFailedEvent) => void) => Promise<PluginListenerHandle>

Will be triggered when native download handling fails. Enable this with handleDownloads: true when opening the webview.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------------- | | eventName | 'downloadFailed' | | listenerFunc | (event: DownloadFailedEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.6.0

addListener('popupWindowOpened', ...)

addListener(eventName: 'popupWindowOpened', listenerFunc: (event: PopupWindowEvent) => void) => Promise<PluginListenerHandle>

Will be triggered whenever a page opens a popup/new window. Use the returned popup id with executeScript, postMessage, show, hide, and close.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------- | | eventName | 'popupWindowOpened' | | listenerFunc | (event: PopupWindowEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.6.0

addListener('proxyRequest', ...)

addListener(eventName: 'proxyRequest', listenerFunc: (event: ProxyRequest) => void) => Promise<PluginListenerHandle>

Listen for proxied requests delegated by the native runtime. Prefer addProxyHandler() instead of calling this directly.

| Param | Type | | ------------------ | ------------------------------------------------------------------------- | | eventName | 'proxyRequest' | | listenerFunc | (event: ProxyRequest) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.6.0

addListener('consoleMessage', ...)

addListener(eventName: 'consoleMessage', listenerFunc: (event: ConsoleMessageEvent) => void) => Promise<PluginListenerHandle>

Listen for JavaScript console output emitted by the managed page. Enable this with captureConsoleLogs: true when opening the webview.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------------- | | eventName | 'consoleMessage' | | listenerFunc | (event: ConsoleMessageEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.6.0

handleProxyRequest(...)

handleProxyRequest(options: { requestId: string; decision?: ProxyDecision | null; response?: ProxyResponse | null; webviewId?: string; phase?: 'outbound' | 'inbound'; }) => Promise<void>

Internal method used by addProxyHandler() to send a proxy decision back to native. Forward the original phase when replying to a manual proxyRequest listener.

| Param | Type | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | options | { requestId: string; decision?: ProxyDecision | null; response?: ProxyResponse | null; webviewId?: string; phase?: 'outbound' | 'inbound'; } |

Since: 8.6.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 1.0.0

reload(...)

reload(options?: { id?: string | undefined; } | undefined) => Promise<any>

Reload the current web page.

| Param | Type | | ------------- | ----------------------------- | | options | { id?: string; } |

Returns: Promise<any>

Since: 1.0.0

updateDimensions(...)

updateDimensions(options: DimensionOptions & { id?: string; }) => Promise<void>

Update the dimensions of the webview. Allows changing the size and position of the webview at runtime. When id is omitted, targets the active webview.

| Param | Type | Description | | ------------- | -------------------------------------------------------------------------------- | --------------------------------------- | | options | DimensionOptions & { id?: string; } | Dimension options (width, height, x, y) |

setFullscreen(...)

setFullscreen(options: { enabled: boolean; id?: string; }) => Promise<void>

Enter or exit immersive fullscreen without recreating or reloading the webview. When id is omitted, targets the active webview. Repeated calls are idempotent. Entry requires a visible, frontmost, full-size openWebView on iOS or Android. Missing webviews, invalid arguments, custom dimensions, behind-host presentations, and the Web platform reject. Use the opening fullscreen option for an initially hidden webview. Disabling also cancels any pending fullscreen-at-launch request.

Native exit controls, backgrounding, hiding, closing, cross-origin navigation, and renderer termination restore the original chrome even when host JavaScript cannot respond.

| Param | Type | | ------------- | ----------------------------------------------- | | options | { enabled: boolean; id?: string; } |

getFullscreen(...)

getFullscreen(options?: { id?: string | undefined; } | undefined) => Promise<{ enabled: boolean; }>

Read the applied host-controlled fullscreen state of an openWebView. When id is omitted, targets the active webview. Initially hidden fullscreen webviews report false until their first presentation. Missing webviews and Web usage reject. HTML/video fullscreen does not change this value.

| Param | Type | | ------------- | ----------------------------- | | options | { id?: string; } |

Returns: Promise<{ enabled: boolean; }>

setEnabledSafeTopMargin(...)

setEnabledSafeTopMargin(options: { enabled: boolean; id?: string; }) => Promise<void>

Sets the enabled safe top margin of the webview at runtime. When id is omitted, targets the active webview. On Web, this method is a no-op and resolves without changing layout.

| Param | Type | | ------------- | ----------------------------------------------- | | options | { enabled: boolean; id?: string; } |

setEnabledSafeBottomMargin(...)

setEnabledSafeBottomMargin(options: { enabled: boolean; id?: string; }) => Promise<void>

Sets the enabled safe bottom margin of the webview at runtime. When id is omitted, targets the active webview. On Web, this method is a no-op and resolves without changing layout.

| Param | Type | | ------------- | ----------------------------------------------- | | options | { enabled: boolean; id?: string; } |

openSecureWindow(...)

openSecureWindow(options: OpenSecureWindowOptions) => Promise<OpenSecureWindowResponse>

Opens a secured window for OAuth2 authentication.

On web, the redirect page should post the final URL to a BroadcastChannel and close itself. On mobile, register a custom redirect URI scheme (for example myapp://oauth_callback/) in Info.plist and AndroidManifest.xml. See the README section "openSecureWindow (OAuth)" for full setup examples.

| Param | Type | Description | | ------------- | --------------------------------------------------------------------------- | ------------------------------------------- | | options | OpenSecureWindowOptions | - the options for the openSecureWindow call |

Returns: Promise<OpenSecureWindowResponse>

Interfaces

OpenOptions

| Prop | Type | Description | Default | Since | | ---------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | | url | string | Target URL to load. Remote http:// and https:// URLs are loaded as-is. Relative bundled paths such as /index.html are not supported; use openWebView() instead. | | 0.1.0 | | isPresentAfterPageLoad | boolean | if true, the browser will be presented after the page is loaded, if false, the browser will be presented immediately. | | 0.1.0 | | preventDeeplink | boolean | if true the deeplink will not be opened, if false the deeplink will be opened when clicked on the link | | 0.1.0 | | toolbarColor | string | Toolbar background color in hex format (e.g., "#1A1A2E"). Applied to both light and dark color schemes. Also sets the navigation bar color to match. Android only — ignored on iOS. | | 8.2.0 | | urlBarHidingEnabled | boolean | Whether the URL bar should auto-hide when the user scrolls down. The bar reappears on any upward scroll. Android only — ignored on iOS. | false | 8.2.0 | | showTitle | boolean | Show the page's HTML <title> in the toolbar instead of the raw URL. The true URL is still visible when the user taps the title area. Android only — ignored on iOS. | false | 8.2.0 | | showArrow | boolean | Replace the default "X" close icon with a back arrow. Makes the Custom Tab feel like a native navigation push rather than a modal overlay. Android only — ignored on iOS. | false | 8.2.0 | | disableShare | boolean | Remove the share action from the overflow menu. Android only — ignored on iOS. | false | 8.2.0 | | disableBookmark | boolean | Hide the bookmark star icon in the overflow menu. Uses an undocumented Chromium intent extra — may stop working on future Chrome updates. Android only — ignored on iOS. | false | 8.2.0 | | disableDownload | boolean | Hide the download icon in the overflow menu. Uses an u

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@capgo/capacitor-inappbrowser

Key features

Why InAppBrowser?

Documentation

Compatibility

Install

Usage

Common use cases

Show Ionic UI over a live browser page

Build a partial-screen browser or bottom sheet

Keep checkout, auth, or support sessions private

Share host WebView cookies for SSO (iOS 17+)

Keep multiple browser instances ready

Listen to console output from the managed page

Hide from the native close button and brand the toolbar title

Embed advanced web app flows

Customize Chrome Custom Tab Appearance (Android)

Open WebView with Custom Dimensions

Open WebView with Safe Margin

Fullscreen at launch and during a session

Extend content behind the status bar

Proxy examples

Block one request natively

Stub one script from JavaScript

Rewrite an outbound API request in JavaScript

Test app and code:

Camera usage

Android

iOS

Microphone usage

Android

iOS

Location usage

Android

iOS

Two way communication

Main app to inappbrowser, detail object is mendatory

Receive event from native in the inappbrowser

Send event from inappbrowser to main app, detail object is mendatory

Receive event from inappbrowser in the main app

Close inappbrowser from inappbrowser itself

Google Pay (Android)

1. Enable the option when opening the browser

2. Add Payment Request intent queries to your AndroidManifest.xml

3. Require WebView 120 or later

openSecureWindow (OAuth)

Web

Mobile

Bundled local assets

API

goBack(...)

open(...)

clearCookies(...)

clearAllCookies(...)

clearCache(...)

clearAllBrowsingData()

getCookies(...)

close(...)

hide(...)

show(...)

sendToBack(...)

bringToFront(...)

dispatchInputEvent(...)

openWebView(...)

executeScript(...)

postMessage(...)

takeScreenshot(...)

setUrl(...)

addListener('urlChangeEvent', ...)

addListener('fullscreenChange', ...)

addListener('buttonNearDoneClick', ...)

addListener('closeEvent', ...)

addListener('hideEvent', ...)

addListener('confirmBtnClicked', ...)

2. Add Payment Request intent queries to your `AndroidManifest.xml`