Capacitor Plugins
Choose the right plugin, install it correctly, and prove it is linked natively.
When to Use
TRIGGER when:
- User asks "which plugin should I use for X?" or compares plugin options.
- User needs a native capability (camera, files, location, biometrics, payments, auth, sensors, storage, media, calendar, contacts, health, on-device LLM).
- A plugin call fails after install:
"X" plugin is not implemented on ios|android|web, UNIMPLEMENTED, unable to find plugin, or an OS-PLUG-* code.
- User needs the right
Info.plist / AndroidManifest.xml / variables.gradle entries for a plugin.
Do not use (load the sibling skill instead):
- Push notification setup, FCM/APNs keys:
capacitor-push-notifications
- Splash screen assets and timing:
capacitor-splash-screen
- Keyboard overlap, accessory bar, resize:
capacitor-keyboard
- Universal Links / App Links:
capacitor-deep-linking
- OTA live updates:
capgo-live-updates
- Migrating plugin source code across Capacitor majors:
capacitor-plugin-upgrades (and capacitor-plugin-upgrade-v8-to-v9)
- Adding Swift Package Manager support to a plugin:
capacitor-plugin-spm-support; moving an app to SPM: cocoapods-to-spm
- AppDelegate/SceneDelegate lifecycle changes:
capacitor-uiscene-migration
- Upgrading the app's Capacitor major:
capacitor-app-upgrades
- SQL storage migrations:
sqlite-to-fast-sql
Version Facts (October 2026)
- Capacitor stable: 8.5.x (
latest). Capacitor 9 is 9.0.0-alpha on the next dist-tag. Official plugins follow: most v8 plugins are 8.x on latest and 9.0.0-alpha on next.
- Plugin major must match the app's Capacitor major. Plugins for older majors use
latest-<major> tags, e.g. npm install @capacitor/camera@latest-7.
- Some official plugins have independent versions (file-transfer 2.x, file-viewer 2.x, inappbrowser 4.x, privacy-screen 2.x, barcode-scanner 3.x, background-runner 3.x, calendar/contacts/health-fitness 1.x). Check
npm view <pkg> peerDependencies instead of matching the number.
@capgo/* plugins use the Capacitor major as their own major (8.x for Capacitor 8). LTS tags such as lts-v7 exist on some packages.
- Capacitor 9: iOS 16 min, Android minSdk 26. Plugins that previously needed
minSdkVersion = 26 (inappbrowser, barcode-scanner) stop needing a bump.
Procedure
Inspect first. Read package.json (@capacitor/core version), capacitor.config.*, and check whether iOS uses SPM (ios/App/CapApp-SPM/Package.swift) or CocoaPods (ios/App/Podfile). Run npx cap ls to see what is already linked.
Pick the package.
- An official
@capacitor/* package exists and covers the need: default to it. Load its reference from the index below.
- No official package, or it lacks a required feature: load
references/capgo-plugin-index.md and pick the exact @capgo/* name. State why it fits better.
- Never recommend a package name that is not in a reference file without checking
npm view <pkg> version first.
Install with the matching major:
npm install @capacitor/<name> # or @capgo/<name>
npx cap sync
Add native config from the reference: usage-description keys, manifest permissions, variables.gradle minSdk/library versions, capabilities/entitlements, AppDelegate hooks. Missing iOS usage strings crash the app on first access.
Ask the user before raising minSdkVersion, adding entitlements (HealthKit, Push), or enabling exact alarms: these affect store review and device reach.
Verify (next section), then run on a real device for anything involving camera, health, LLM, BLE, or push.
Capgo Plugin Index
references/capgo-plugin-index.md is the complete Capgo plugin source, generated from Cap-go GitHub package.json and src/definitions.ts: npm name, purpose, install command, platforms, key API methods, docs and repo links for every public non-archived package. references/capgo-plugin-catalog.md is the compact table of the same set. Load the index before recommending any @capgo/* package and use the exact name from it.
Regenerate both after Cap-go org changes (repository maintainers only):
GITHUB_TOKEN=$(gh auth token) node scripts/generate-capgo-plugin-index.mjs
Verification
npx cap sync # must finish without "[error]" lines
npx cap ls # lists "Found N Capacitor plugins for ios/android"; plugin must appear for each platform
- Android:
android/app/capacitor.build.gradle contains implementation project(':capacitor-<name>') and android/capacitor.settings.gradle has the matching include. Then cd android && ./gradlew assembleDebug.
- iOS SPM:
ios/App/CapApp-SPM/Package.swift lists the plugin package. iOS CocoaPods: ios/App/Podfile has the pod and pod install succeeded. Build in Xcode or npx cap run ios.
- Grep for leftovers when replacing a plugin:
grep -rn "<old-package>" src android ios package.json.
- Feature-detect at runtime:
Capacitor.isPluginAvailable('Camera') and Capacitor.getPlatform().
Error Handling
| Error |
Cause |
Fix |
"Camera" plugin is not implemented on ios (or android/web) |
Native side not linked, or no web implementation |
npx cap sync, rebuild the native app (live reload does not pick up new native code), check npx cap ls. On web, guard with Capacitor.isNativePlatform(). |
"Camera.takePhoto()" is not implemented on ios |
Plugin linked but JS and native versions differ, or method is platform-specific |
Align JS and native versions, npx cap sync, clean build. Check the reference for platform-only methods. |
UNIMPLEMENTED error code |
Method not available on this platform/OS version |
Branch on platform; see reference "Notes". |
Android log unable to find plugin : X |
Plugin class not registered/included |
Confirm capacitor.build.gradle entry, re-sync, Gradle sync in Android Studio. |
iOS log Error loading plugin X for call. Check that the pluginId is correct |
Plugin not in the iOS build |
Re-sync; check Package.swift (SPM) or Podfile; clean build folder. |
| App crashes on first camera/contacts/calendar/location access (iOS) |
Missing NS*UsageDescription key |
Add the key listed in the reference to Info.plist. |
Manifest merger failed : uses-sdk:minSdkVersion 24 cannot be smaller than version 26 declared in library [...] |
Plugin needs higher minSdk |
Raise minSdkVersion in android/variables.gradle (ask the user first). |
OS-PLUG-* codes (e.g. OS-PLUG-CAMR-0003) |
Structured native errors in OutSystems-based official plugins |
Look up the code in the plugin reference (camera, file-transfer, calendar, contacts list the common ones). |
npm ERESOLVE peer @capacitor/core conflict |
Plugin major does not match app major |
Install the matching tag (@latest-7, @next for v9 alpha) or upgrade the app with capacitor-app-upgrades. |
Reference Index
Only load a reference when its plugin is in play.
Official @capacitor/* packages (install, native config, usage, gotchas):
| Need |
Reference |
| Action sheet |
references/capacitor-action-sheet.md |
| Open other apps / check installed |
references/capacitor-app-launcher.md |
| App state, back button, URL open events |
references/capacitor-app.md |
| JS tasks in background |
references/capacitor-background-runner.md |
| Barcode / QR scan |
references/capacitor-barcode-scanner.md |
| OAuth-safe in-app browser (SFSafariViewController / Custom Tabs) |
references/capacitor-browser.md |
| Calendar events |
references/capacitor-calendar.md |
Camera, gallery, video (8.1+ API, getPhoto migration) |
references/capacitor-camera.md |
| Clipboard |
references/capacitor-clipboard.md |
| Contacts |
references/capacitor-contacts.md |
| Native cookies (core) |
references/capacitor-cookies.md |
| Device info / id / battery |
references/capacitor-device.md |
| Native alert/confirm/prompt |
references/capacitor-dialog.md |
| Upload/download with progress |
references/capacitor-file-transfer.md |
| Open/preview documents |
references/capacitor-file-viewer.md |
| File read/write |
references/capacitor-filesystem.md |
| Location (foreground) |
references/capacitor-geolocation.md |
| Google Maps |
references/capacitor-google-maps.md |
| HealthKit / Health Connect |
references/capacitor-health-fitness.md |
| Haptics |
references/capacitor-haptics.md |
| Native HTTP (core, CORS bypass) |
references/capacitor-http.md |
| WebView / system / external browser |
references/capacitor-inappbrowser.md |
| Keyboard API basics |
references/capacitor-keyboard.md |
| On-device LLM (experimental) |
references/capacitor-local-llm.md |
| Local notifications |
references/capacitor-local-notifications.md |
| Accelerometer / orientation |
references/capacitor-motion.md |
| Connectivity |
references/capacitor-network.md |
| Key/value storage |
references/capacitor-preferences.md |
| Hide app switcher snapshot / block screenshots |
references/capacitor-privacy-screen.md |
| Push API summary |
references/capacitor-push-notifications.md |
| Orientation lock |
references/capacitor-screen-orientation.md |
| TalkBack / VoiceOver state, TTS |
references/capacitor-screen-reader.md |
| Share sheet |
references/capacitor-share.md |
| Splash API summary |
references/capacitor-splash-screen.md |
| Status bar (legacy) |
references/capacitor-status-bar.md |
| Edge-to-edge system bars (core, preferred on Android 16+) |
references/capacitor-system-bars.md |
| WebView text zoom |
references/capacitor-text-zoom.md |
| Toast |
references/capacitor-toast.md |
| Apple Watch UI (experimental) |
references/capacitor-watch.md |
Capgo plugins: references/capgo-plugin-index.md (145 packages: install, platforms, key APIs, docs) and references/capgo-plugin-catalog.md (compact table).
Capgo Quick Picks
| Need |
Package |
| Background geolocation, geofencing |
@capgo/background-geolocation |
| Custom camera preview / overlays |
@capgo/camera-preview |
| Biometric login + secure credentials |
@capgo/capacitor-native-biometric |
| Apple/Google/Facebook sign-in |
@capgo/capacitor-social-login |
| Subscriptions / IAP |
@capgo/native-purchases (revenue strategy: subscription-app-revenue) |
| Apple Pay / Google Pay |
@capgo/capacitor-pay |
| Fast native SQLite |
@capgo/capacitor-fast-sql |
| Native file ops / picking |
@capgo/capacitor-file, @capgo/capacitor-file-picker |
In-app browser with JS injection, postMessage, screenshots |
@capgo/capacitor-inappbrowser |
| WebView killed in background, relaunch |
@capgo/capacitor-webview-guardian |
| App Attest / Play Integrity |
@capgo/capacitor-app-attest |
| OTA live updates |
@capgo/capacitor-updater (setup: capgo-live-updates) |
| Dev live reload |
@capgo/capacitor-live-reload |
Traps:
- Do not install two plugins that own the same native surface (e.g. two in-app browsers or two biometric plugins) without a reason; they can conflict on delegates and manifest entries.
- Firebase: install the individual
@capgo/capacitor-firebase-* packages; there is no umbrella @capgo/capacitor-firebase package on npm.
- Cordova plugins still work but on Capacitor 9 they pull in the Cordova runtime; prefer a Capacitor-native equivalent (
cordova-to-capacitor).
Resources
1---2name: capacitor-plugins3description: Pick, install, and wire up Capacitor plugins for native features (camera, filesystem, geolocation, biometrics, in-app purchases, social login, SQLite, calendar, contacts, health, BLE, NFC, etc.). Covers official @capacitor/* packages (Capacitor 8.5 stable, 9 alpha on next) plus the 145-package @capgo/* index, native permission keys (Info.plist, AndroidManifest, variables.gradle minSdk), npx cap sync / cap ls verification, and errors like '"Camera" plugin is not implemented on ios', 'unable to find plugin', UNIMPLEMENTED, and OS-PLUG-* codes. Use for "which plugin should I use for X", adding a plugin, or a plugin call failing after install. Do not use for push setup (capacitor-push-notifications), splash assets (capacitor-splash-screen), keyboard layout (capacitor-keyboard), deep links (capacitor-deep-linking), OTA updates (capgo-live-updates), upgrading plugin source code (capacitor-plugin-upgrades), or adding SPM to a plugin (capacitor-plugin-spm-support).4metadata:5 source: https://skillmd.com/skills/tuyv/capacitor-plugins6---78# Capacitor Plugins910Choose the right plugin, install it correctly, and prove it is linked natively.1112## When to Use1314TRIGGER when:1516- User asks "which plugin should I use for X?" or compares plugin options.17- User needs a native capability (camera, files, location, biometrics, payments, auth, sensors, storage, media, calendar, contacts, health, on-device LLM).18- A plugin call fails after install: `"X" plugin is not implemented on ios|android|web`, `UNIMPLEMENTED`, `unable to find plugin`, or an `OS-PLUG-*` code.19- User needs the right `Info.plist` / `AndroidManifest.xml` / `variables.gradle` entries for a plugin.2021Do not use (load the sibling skill instead):2223- Push notification setup, FCM/APNs keys: `capacitor-push-notifications`24- Splash screen assets and timing: `capacitor-splash-screen`25- Keyboard overlap, accessory bar, resize: `capacitor-keyboard`26- Universal Links / App Links: `capacitor-deep-linking`27- OTA live updates: `capgo-live-updates`28- Migrating plugin *source code* across Capacitor majors: `capacitor-plugin-upgrades` (and `capacitor-plugin-upgrade-v8-to-v9`)29- Adding Swift Package Manager support to a plugin: `capacitor-plugin-spm-support`; moving an app to SPM: `cocoapods-to-spm`30- AppDelegate/SceneDelegate lifecycle changes: `capacitor-uiscene-migration`31- Upgrading the app's Capacitor major: `capacitor-app-upgrades`32- SQL storage migrations: `sqlite-to-fast-sql`3334## Version Facts (October 2026)3536- Capacitor stable: 8.5.x (`latest`). Capacitor 9 is `9.0.0-alpha` on the `next` dist-tag. Official plugins follow: most v8 plugins are `8.x` on `latest` and `9.0.0-alpha` on `next`.37- Plugin major must match the app's Capacitor major. Plugins for older majors use `latest-<major>` tags, e.g. `npm install @capacitor/camera@latest-7`.38- Some official plugins have independent versions (file-transfer 2.x, file-viewer 2.x, inappbrowser 4.x, privacy-screen 2.x, barcode-scanner 3.x, background-runner 3.x, calendar/contacts/health-fitness 1.x). Check `npm view <pkg> peerDependencies` instead of matching the number.39- `@capgo/*` plugins use the Capacitor major as their own major (8.x for Capacitor 8). LTS tags such as `lts-v7` exist on some packages.40- Capacitor 9: iOS 16 min, Android minSdk 26. Plugins that previously needed `minSdkVersion = 26` (inappbrowser, barcode-scanner) stop needing a bump.4142## Procedure43441. **Inspect first.** Read `package.json` (`@capacitor/core` version), `capacitor.config.*`, and check whether iOS uses SPM (`ios/App/CapApp-SPM/Package.swift`) or CocoaPods (`ios/App/Podfile`). Run `npx cap ls` to see what is already linked.452. **Pick the package.**46 - An official `@capacitor/*` package exists and covers the need: default to it. Load its reference from the index below.47 - No official package, or it lacks a required feature: load `references/capgo-plugin-index.md` and pick the exact `@capgo/*` name. State why it fits better.48 - Never recommend a package name that is not in a reference file without checking `npm view <pkg> version` first.493. **Install with the matching major:**5051 ```bash52 npm install @capacitor/<name> # or @capgo/<name>53 npx cap sync54 ```55564. **Add native config** from the reference: usage-description keys, manifest permissions, `variables.gradle` minSdk/library versions, capabilities/entitlements, AppDelegate hooks. Missing iOS usage strings crash the app on first access.575. **Ask the user** before raising `minSdkVersion`, adding entitlements (HealthKit, Push), or enabling exact alarms: these affect store review and device reach.586. **Verify** (next section), then run on a real device for anything involving camera, health, LLM, BLE, or push.5960## Capgo Plugin Index6162`references/capgo-plugin-index.md` is the complete Capgo plugin source, generated from Cap-go GitHub `package.json` and `src/definitions.ts`: npm name, purpose, install command, platforms, key API methods, docs and repo links for every public non-archived package. `references/capgo-plugin-catalog.md` is the compact table of the same set. Load the index before recommending any `@capgo/*` package and use the exact name from it.6364Regenerate both after Cap-go org changes (repository maintainers only):6566```bash67GITHUB_TOKEN=$(gh auth token) node scripts/generate-capgo-plugin-index.mjs68```6970## Verification7172```bash73npx cap sync # must finish without "[error]" lines74npx cap ls # lists "Found N Capacitor plugins for ios/android"; plugin must appear for each platform75```7677- Android: `android/app/capacitor.build.gradle` contains `implementation project(':capacitor-<name>')` and `android/capacitor.settings.gradle` has the matching `include`. Then `cd android && ./gradlew assembleDebug`.78- iOS SPM: `ios/App/CapApp-SPM/Package.swift` lists the plugin package. iOS CocoaPods: `ios/App/Podfile` has the pod and `pod install` succeeded. Build in Xcode or `npx cap run ios`.79- Grep for leftovers when replacing a plugin: `grep -rn "<old-package>" src android ios package.json`.80- Feature-detect at runtime: `Capacitor.isPluginAvailable('Camera')` and `Capacitor.getPlatform()`.8182## Error Handling8384| Error | Cause | Fix |85|-------|-------|-----|86| `"Camera" plugin is not implemented on ios` (or `android`/`web`) | Native side not linked, or no web implementation | `npx cap sync`, rebuild the native app (live reload does not pick up new native code), check `npx cap ls`. On web, guard with `Capacitor.isNativePlatform()`. |87| `"Camera.takePhoto()" is not implemented on ios` | Plugin linked but JS and native versions differ, or method is platform-specific | Align JS and native versions, `npx cap sync`, clean build. Check the reference for platform-only methods. |88| `UNIMPLEMENTED` error code | Method not available on this platform/OS version | Branch on platform; see reference "Notes". |89| Android log `unable to find plugin : X` | Plugin class not registered/included | Confirm `capacitor.build.gradle` entry, re-sync, Gradle sync in Android Studio. |90| iOS log `Error loading plugin X for call. Check that the pluginId is correct` | Plugin not in the iOS build | Re-sync; check `Package.swift` (SPM) or Podfile; clean build folder. |91| App crashes on first camera/contacts/calendar/location access (iOS) | Missing `NS*UsageDescription` key | Add the key listed in the reference to `Info.plist`. |92| `Manifest merger failed : uses-sdk:minSdkVersion 24 cannot be smaller than version 26 declared in library [...]` | Plugin needs higher minSdk | Raise `minSdkVersion` in `android/variables.gradle` (ask the user first). |93| `OS-PLUG-*` codes (e.g. `OS-PLUG-CAMR-0003`) | Structured native errors in OutSystems-based official plugins | Look up the code in the plugin reference (camera, file-transfer, calendar, contacts list the common ones). |94| npm `ERESOLVE` peer `@capacitor/core` conflict | Plugin major does not match app major | Install the matching tag (`@latest-7`, `@next` for v9 alpha) or upgrade the app with `capacitor-app-upgrades`. |9596## Reference Index9798Only load a reference when its plugin is in play.99100Official `@capacitor/*` packages (install, native config, usage, gotchas):101102| Need | Reference |103|------|-----------|104| Action sheet | `references/capacitor-action-sheet.md` |105| Open other apps / check installed | `references/capacitor-app-launcher.md` |106| App state, back button, URL open events | `references/capacitor-app.md` |107| JS tasks in background | `references/capacitor-background-runner.md` |108| Barcode / QR scan | `references/capacitor-barcode-scanner.md` |109| OAuth-safe in-app browser (SFSafariViewController / Custom Tabs) | `references/capacitor-browser.md` |110| Calendar events | `references/capacitor-calendar.md` |111| Camera, gallery, video (8.1+ API, `getPhoto` migration) | `references/capacitor-camera.md` |112| Clipboard | `references/capacitor-clipboard.md` |113| Contacts | `references/capacitor-contacts.md` |114| Native cookies (core) | `references/capacitor-cookies.md` |115| Device info / id / battery | `references/capacitor-device.md` |116| Native alert/confirm/prompt | `references/capacitor-dialog.md` |117| Upload/download with progress | `references/capacitor-file-transfer.md` |118| Open/preview documents | `references/capacitor-file-viewer.md` |119| File read/write | `references/capacitor-filesystem.md` |120| Location (foreground) | `references/capacitor-geolocation.md` |121| Google Maps | `references/capacitor-google-maps.md` |122| HealthKit / Health Connect | `references/capacitor-health-fitness.md` |123| Haptics | `references/capacitor-haptics.md` |124| Native HTTP (core, CORS bypass) | `references/capacitor-http.md` |125| WebView / system / external browser | `references/capacitor-inappbrowser.md` |126| Keyboard API basics | `references/capacitor-keyboard.md` |127| On-device LLM (experimental) | `references/capacitor-local-llm.md` |128| Local notifications | `references/capacitor-local-notifications.md` |129| Accelerometer / orientation | `references/capacitor-motion.md` |130| Connectivity | `references/capacitor-network.md` |131| Key/value storage | `references/capacitor-preferences.md` |132| Hide app switcher snapshot / block screenshots | `references/capacitor-privacy-screen.md` |133| Push API summary | `references/capacitor-push-notifications.md` |134| Orientation lock | `references/capacitor-screen-orientation.md` |135| TalkBack / VoiceOver state, TTS | `references/capacitor-screen-reader.md` |136| Share sheet | `references/capacitor-share.md` |137| Splash API summary | `references/capacitor-splash-screen.md` |138| Status bar (legacy) | `references/capacitor-status-bar.md` |139| Edge-to-edge system bars (core, preferred on Android 16+) | `references/capacitor-system-bars.md` |140| WebView text zoom | `references/capacitor-text-zoom.md` |141| Toast | `references/capacitor-toast.md` |142| Apple Watch UI (experimental) | `references/capacitor-watch.md` |143144Capgo plugins: `references/capgo-plugin-index.md` (145 packages: install, platforms, key APIs, docs) and `references/capgo-plugin-catalog.md` (compact table).145146## Capgo Quick Picks147148| Need | Package |149|------|---------|150| Background geolocation, geofencing | `@capgo/background-geolocation` |151| Custom camera preview / overlays | `@capgo/camera-preview` |152| Biometric login + secure credentials | `@capgo/capacitor-native-biometric` |153| Apple/Google/Facebook sign-in | `@capgo/capacitor-social-login` |154| Subscriptions / IAP | `@capgo/native-purchases` (revenue strategy: `subscription-app-revenue`) |155| Apple Pay / Google Pay | `@capgo/capacitor-pay` |156| Fast native SQLite | `@capgo/capacitor-fast-sql` |157| Native file ops / picking | `@capgo/capacitor-file`, `@capgo/capacitor-file-picker` |158| In-app browser with JS injection, `postMessage`, screenshots | `@capgo/capacitor-inappbrowser` |159| WebView killed in background, relaunch | `@capgo/capacitor-webview-guardian` |160| App Attest / Play Integrity | `@capgo/capacitor-app-attest` |161| OTA live updates | `@capgo/capacitor-updater` (setup: `capgo-live-updates`) |162| Dev live reload | `@capgo/capacitor-live-reload` |163164Traps:165166- Do not install two plugins that own the same native surface (e.g. two in-app browsers or two biometric plugins) without a reason; they can conflict on delegates and manifest entries.167- Firebase: install the individual `@capgo/capacitor-firebase-*` packages; there is no umbrella `@capgo/capacitor-firebase` package on npm.168- Cordova plugins still work but on Capacitor 9 they pull in the Cordova runtime; prefer a Capacitor-native equivalent (`cordova-to-capacitor`).169170## Resources171172- Official plugin docs: https://capacitorjs.com/docs/apis173- Capgo plugin docs: https://capgo.app/docs/plugins/174- Capgo GitHub: https://github.com/Cap-go