@capgo/capacitor-intent-launcher

Launch Android intents and open system settings screens from your Capacitor app, and open iOS settings pages. Send users straight to the setting they need to change.

🤖 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-intent-launcher in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-intent-launcher to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Android intents: startActivityAsync() starts any activity with action, data, extras and flags, and returns the result.
• iOS settings: openIOSSettings() opens a settings screen.
• Open apps: openApplication() launches another app by package name on Android.
• App icons: getApplicationIconAsync() returns an installed app's icon as base64 on Android.
• Platforms: iOS and Android. Not available on web.

Why Capacitor Intent Launcher?

A simple, free, and lightweight intent launcher plugin for both Android and iOS:

• System settings access - Open any Android settings screen (WiFi, Bluetooth, Location, etc.) or iOS settings screens
• iOS settings support - Open iOS settings screens including app settings, WiFi, Bluetooth, notifications, and more
• App launching - Open any installed application by package name (Android)
• App icon retrieval - Get application icons as base64-encoded images (Android)
• Full intent support - Pass extras, flags, data URIs, and MIME types (Android)
• Activity results - Receive result codes and data from launched activities (Android)
• Zero dependencies - Minimal footprint, no bloat

Perfect for apps that need to guide users to system settings on both platforms.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/intent-launcher/

Compatibility

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-intent-launcher` 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-intent-launcher
npx cap sync

Android

Works out of the box. No additional configuration required.

Opening Android Settings Screens

The plugin provides access to all Android system settings screens through the ActivityAction enum. Here are common examples:

import { IntentLauncher, ActivityAction } from '@capgo/capacitor-intent-launcher';

// Open main settings screen
await IntentLauncher.startActivityAsync({
  action: ActivityAction.SETTINGS
});

// Open WiFi settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.WIFI_SETTINGS
});

// Open Bluetooth settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.BLUETOOTH_SETTINGS
});

// Open Location settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.LOCATION_SOURCE_SETTINGS
});

// Open Display settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.DISPLAY_SETTINGS
});

// Open Sound settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.SOUND_SETTINGS
});

// Open Notification settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.NOTIFICATION_SETTINGS
});

Opening App-Specific Settings

You can open settings for a specific app by passing the package name:

// Open your app's settings page
await IntentLauncher.startActivityAsync({
  action: ActivityAction.APPLICATION_DETAILS_SETTINGS,
  data: 'package:com.yourapp.package'
});

// Open notification settings for your app
await IntentLauncher.startActivityAsync({
  action: ActivityAction.APP_NOTIFICATION_SETTINGS,
  extra: {
    'android.provider.extra.APP_PACKAGE': 'com.yourapp.package'
  }
});

Launching Other Apps

// Open an app by package name
await IntentLauncher.openApplication({
  packageName: 'com.google.android.gm' // Gmail
});

// Get an app's icon
const { icon } = await IntentLauncher.getApplicationIconAsync({
  packageName: 'com.google.android.gm'
});
// icon is a base64-encoded PNG: 'data:image/png;base64,...'

Advanced Intent Options

You can pass additional options like extras, flags, and MIME types:

// Open a content picker
await IntentLauncher.startActivityAsync({
  action: ActivityAction.GET_CONTENT,
  type: 'image/*',  // MIME type
  category: 'android.intent.category.OPENABLE'
});

// Open a URL in the browser
await IntentLauncher.startActivityAsync({
  action: ActivityAction.VIEW,
  data: 'https://example.com'
});

// Send text to another app
await IntentLauncher.startActivityAsync({
  action: ActivityAction.SEND,
  type: 'text/plain',
  extra: {
    'android.intent.extra.TEXT': 'Hello World!'
  }
});

// Make a phone call (requires CALL_PHONE permission)
await IntentLauncher.startActivityAsync({
  action: ActivityAction.CALL,
  data: 'tel:+1234567890'
});

// Open the dialer with a number (no permission required)
await IntentLauncher.startActivityAsync({
  action: ActivityAction.DIAL,
  data: 'tel:+1234567890'
});

Handling Activity Results

The startActivityAsync method returns a result with status information:

const result = await IntentLauncher.startActivityAsync({
  action: ActivityAction.LOCATION_SOURCE_SETTINGS
});

console.log('Result code:', result.resultCode);
// resultCode: -1 = Success, 0 = Canceled, 1+ = Custom user codes

if (result.data) {
  console.log('Data URI:', result.data);
}

if (result.extra) {
  console.log('Extra data:', result.extra);
}

Common Use Cases

Guide users to enable permissions:

// Location permission
await IntentLauncher.startActivityAsync({
  action: ActivityAction.LOCATION_SOURCE_SETTINGS
});

// Battery optimization settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.IGNORE_BATTERY_OPTIMIZATION_SETTINGS
});

// Overlay permission (draw over other apps)
await IntentLauncher.startActivityAsync({
  action: ActivityAction.MANAGE_OVERLAY_PERMISSION,
  data: 'package:com.yourapp.package'
});

Network settings:

// WiFi settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.WIFI_SETTINGS
});

// Mobile data settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.DATA_USAGE_SETTINGS
});

// Airplane mode settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.AIRPLANE_MODE_SETTINGS
});

Security settings:

// Biometric enrollment
await IntentLauncher.startActivityAsync({
  action: ActivityAction.BIOMETRIC_ENROLL
});

// Fingerprint settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.FINGERPRINT_SETTINGS
});

// Security settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.SECURITY_SETTINGS
});

Android Version Compatibility

Some settings actions are only available on specific Android versions. The plugin includes platform version information in the ActivityAction enum comments (e.g., @platform Android 12+). If you use an action that's not available on the device's Android version, the intent may fail or fall back to a general settings screen.

Error Handling

Always wrap intent calls in try-catch blocks:

try {
  await IntentLauncher.startActivityAsync({
    action: ActivityAction.WIFI_SETTINGS
  });
} catch (error) {
  console.error('Failed to open settings:', error);
  // Handle error - e.g., show a message to the user
}

iOS

Works out of the box. Use the openIOSSettings() method to open iOS settings screens.

Important: The only officially supported option by Apple is IOSSettings.App which opens your app's settings page. Other options use undocumented URL schemes (App-prefs:) that may break in future iOS versions or could potentially cause App Store rejection.

Note: The iOS Simulator will sometimes only open the Settings app, instead of the specified option. Test on a real device for accurate behavior.

import { IntentLauncher, IOSSettings } from '@capgo/capacitor-intent-launcher';

// Open app settings (officially supported by Apple)
await IntentLauncher.openIOSSettings({ option: IOSSettings.App });

// Open WiFi settings (may not work in all iOS versions)
await IntentLauncher.openIOSSettings({ option: IOSSettings.WiFi });

Web

Not supported. This plugin uses native platform APIs.

API

• startActivityAsync(...)
• openIOSSettings(...)
• openApplication(...)
• getApplicationIconAsync(...)
• getPluginVersion()
• Interfaces
• Type Aliases
• Enums

Capacitor Intent Launcher Plugin for launching Android intents and opening system settings on both Android and iOS.

startActivityAsync(...)

startActivityAsync(options: IntentLauncherParams) => Promise<IntentLauncherResult>

Starts an Android activity for the given action.

Returns: Promise<IntentLauncherResult>

Since: 1.0.0

openIOSSettings(...)

openIOSSettings(options: IOSSettingsParams) => Promise<IOSSettingsResult>

Opens iOS settings screen.

Note: The only officially supported option by Apple is App which opens your app's settings page. Other options may work but are not guaranteed and could break in future iOS versions or cause App Store rejection.

Also note that the iOS Simulator will sometimes only open the Settings app, instead of the specified option.

Returns: Promise<IOSSettingsResult>

Since: 8.2.0

openApplication(...)

openApplication(options: OpenApplicationOptions) => Promise<void>

Opens an application by its package name.

Since: 1.0.0

getApplicationIconAsync(...)

getApplicationIconAsync(options: GetApplicationIconOptions) => Promise<GetApplicationIconResult>

Gets the application icon as a base64-encoded PNG string.

Returns: Promise<GetApplicationIconResult>

Since: 1.0.0

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Interfaces

IntentLauncherResult

Result from starting an activity.

IntentLauncherParams

Options for starting an activity.

IOSSettingsResult

Result from opening iOS settings.

IOSSettingsParams

Options for opening iOS settings.

OpenApplicationOptions

Options for opening an application.

GetApplicationIconResult

Result from getting an application icon.

GetApplicationIconOptions

Options for getting an application icon.

Type Aliases

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

Enums

ResultCode

Credit

Based on the (Expo plugin)[https://docs.expo.dev/versions/latest/sdk/intent-launcher/]