@capgo/capacitor-permissions

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

@capgo/capacitor-permissions gives Capacitor apps one TypeScript API to check and request runtime permissions on iOS, Android, and web. Instead of wiring each feature plugin separately or guessing platform-specific status codes, you work with a single set of permission names and normalized states (granted, denied, blocked, limited, unavailable). Native manifests stay lean: the plugin ships without uses-permission entries or forced Info.plist strings, so store review only sees what your app declares.

Features

• One PermissionName enum for camera, location, notifications, media, contacts, and more across platforms
• check, request, checkMultiple, and requestMultiple with shared AppPermissionState results
• Android shouldShowRationale before re-prompting after a denial
• openSettings for application or notification settings when access is blocked
• requestPreciseLocation for full accuracy on iOS and ACCESS_FINE_LOCATION on Android
• Web implementation via the browser Permissions API for supported types
• Optional scripts/apply-permissions.mjs to add only the Android and iOS declarations you need

Use cases

• Gate a screen until camera or microphone access is granted
• Run a startup audit with checkMultiple and show a single onboarding flow for missing permissions
• Send users to system settings when status is blocked after openSettings
• Request notification permission before registering push tokens
• Upgrade from reduced to precise location when a map feature needs it

Documentation

• Plugin docs on Capgo
• Tutorial: capacitor-permissions
• Capgo live updates

Compatibility

Policy:

• New plugins start at version 8.0.0 (Capacitor 8 baseline).
• Backward compatibility for older Capacitor majors is supported on demand.

Install

npm install @capgo/capacitor-permissions
npx cap sync

With Bun:

bun add @capgo/capacitor-permissions
bunx cap sync

iOS setup

The plugin does not inject usage descriptions into your app. For each PermissionName you call at runtime, add the matching keys to ios/App/App/Info.plist (customize the user-facing strings):

notifications on iOS uses the system notification permission flow; no extra usage string is required for the API itself. Permissions such as activityRecognition, phone, sms, and Android-style media splits are not applicable on iOS and report unavailable when checked.

You can apply the keys above automatically from the plugin repo:

node node_modules/@capgo/capacitor-permissions/scripts/apply-permissions.mjs \
  --project . \
  --permissions camera,microphone,notifications,locationWhenInUse,photoLibrary

(Point --project at your Capacitor app root, the folder that contains ios/ and android/.)

Android setup

The library AndroidManifest.xml declares no <uses-permission> entries. Add only what your app uses to android/app/src/main/AndroidManifest.xml. The plugin targets minSdk 24 (Android 7.0) unless your project overrides minSdkVersion.

reminders and appTrackingTransparency are not Android runtime permissions in this API and return unavailable.

Use the same apply-permissions.mjs script as on iOS to merge declarations into your app manifest.

Web setup

No manifest changes. Supported permissions use navigator.permissions and related APIs (camera, microphone, notifications, locationWhenInUse; locationAlways maps to foreground geolocation only). Others return unavailable. openSettings is not implemented on web.

Usage

import { Permissions } from '@capgo/capacitor-permissions';

export async function ensureCamera(): Promise<boolean> {
  const { status } = await Permissions.check({ permission: 'camera' });
  if (status === 'granted') {
    return true;
  }
  const { status: afterRequest } = await Permissions.request({ permission: 'camera' });
  return afterRequest === 'granted';
}

Check several permissions before showing an onboarding screen:

const { statuses } = await Permissions.checkMultiple({
  permissions: ['camera', 'microphone', 'notifications'],
});
const missing = Object.entries(statuses).filter(([, s]) => s !== 'granted');

When Android reports denied, show context before requesting again:

const { shouldShow } = await Permissions.shouldShowRationale({ permission: 'camera' });
if (shouldShow) {
  // Show your own explanation UI, then:
  await Permissions.request({ permission: 'camera' });
}

If status is blocked, send the user to settings:

await Permissions.openSettings({ type: 'application' });

Example app

The example-app/ project exercises every PermissionName. Apply declarations, sync native projects, then:

cd example-app
bun install
bun run start

API

• check(...)
• request(...)
• checkMultiple(...)
• requestMultiple(...)
• shouldShowRationale(...)
• openSettings(...)
• requestPreciseLocation()
• getPluginVersion()
• Interfaces
• Type Aliases

Cross-platform permissions API for Capacitor apps.

check(...)

check(options: PermissionOptions) => Promise<PermissionStatusResult>

Check the current status of one permission without prompting the user.

Returns: Promise<PermissionStatusResult>

Since: 8.0.0

request(...)

request(options: PermissionOptions) => Promise<PermissionStatusResult>

Request one permission from the user. On Android, shows the system dialog when needed. On iOS, triggers the platform authorization flow for the mapped capability.

Returns: Promise<PermissionStatusResult>

Since: 8.0.0

checkMultiple(...)

checkMultiple(options: MultiplePermissionOptions) => Promise<MultiplePermissionStatusResult>

Check several permissions without prompting.

Returns: Promise<MultiplePermissionStatusResult>

Since: 8.0.0

requestMultiple(...)

requestMultiple(options: MultiplePermissionOptions) => Promise<MultiplePermissionStatusResult>

Request several permissions sequentially so dialogs are not shown on top of each other.

Returns: Promise<MultiplePermissionStatusResult>

Since: 8.0.0

shouldShowRationale(...)

shouldShowRationale(options: PermissionOptions) => Promise<ShouldShowRationaleResult>

Whether Android should show a rationale before requesting again. Returns { shouldShow: false } on iOS and web.

Returns: Promise<ShouldShowRationaleResult>

Since: 8.0.0

openSettings(...)

openSettings(options?: OpenSettingsOptions | undefined) => Promise<void>

Open the application or notification settings screen. Rejects on web with UNIMPLEMENTED.

Since: 8.0.0

requestPreciseLocation()

requestPreciseLocation() => Promise<PermissionStatusResult>

Ask for precise location. On iOS, requests temporary full accuracy when already authorized when-in-use. On Android, requests ACCESS_FINE_LOCATION. On web, returns the geolocation permission status after prompting when possible.

Returns: Promise<PermissionStatusResult>

Since: 8.0.0

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Since: 8.0.0

Interfaces

PermissionStatusResult

Result for a single permission status.

PermissionOptions

Options for checking or requesting a single permission.

MultiplePermissionStatusResult

Result for several permission statuses.

MultiplePermissionOptions

Options for checking or requesting several permissions.

ShouldShowRationaleResult

Result for Android rationale checks.

OpenSettingsOptions

Options for opening system settings.

PluginVersionResult

Plugin version payload.

Type Aliases

AppPermissionState

Normalized permission status returned by every platform implementation.

• granted: the user allowed full access.
• denied: the user has not granted access yet, or Android can show a rationale.
• blocked: the user denied access and the app cannot prompt again without settings.
• limited: partial access (for example iOS limited photo library or reduced location accuracy).
• unavailable: the permission is not supported on this platform or not declared in the app manifest.

'granted' | 'denied' | 'blocked' | 'limited' | 'unavailable'

PermissionName

Logical permission identifiers shared across iOS, Android, and web.

Android-only names include activityRecognition, phone, sms, mediaAudio, mediaImages, and mediaVideo. iOS-only names include reminders and appTrackingTransparency. Web supports a subset via browser APIs (camera, microphone, notifications, locationWhenInUse). On web, locationAlways is an alias of foreground geolocation only; browsers do not expose background location permission.

'camera' | 'microphone' | 'photoLibrary' | 'photoLibraryAddOnly' | 'contacts' | 'calendar' | 'reminders' | 'locationWhenInUse' | 'locationAlways' | 'bluetooth' | 'motion' | 'notifications' | 'speechRecognition' | 'appTrackingTransparency' | 'activityRecognition' | 'phone' | 'sms' | 'mediaAudio' | 'mediaImages' | 'mediaVideo'

Record

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

{ [P in K]: T; }

SettingsType

Settings screen type for openSettings.

'application' | 'notifications'