https://github.com/cap-go/capacitor-sim
Capacitor plugin to get information from device's sim cards
https://github.com/cap-go/capacitor-sim
capacitor capacitor-plugin plugin
Last synced: 10 days ago
JSON representation
Capacitor plugin to get information from device's sim cards
- Host: GitHub
- URL: https://github.com/cap-go/capacitor-sim
- Owner: Cap-go
- License: mpl-2.0
- Created: 2025-10-09T01:18:49.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-06-15T22:49:51.000Z (11 days ago)
- Last Synced: 2026-06-15T23:24:08.813Z (11 days ago)
- Topics: capacitor, capacitor-plugin, plugin
- Language: JavaScript
- Homepage: https://capgo.app/docs/plugins/sim/
- Size: 1000 KB
- Stars: 9
- Watchers: 0
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# @capgo/capacitor-sim
Capacitor plugin to get information from device's sim cards
## Documentation
The most complete doc is available here: https://capgo.app/docs/plugins/sim/
## 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:
```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```
Then use the following prompt:
```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-sim` plugin in my project.
```
If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
```bash
npm install @capgo/capacitor-sim
npx cap sync
```
## Usage
```ts
import { Sim } from '@capgo/capacitor-sim';
const loadSimCards = async () => {
const { simCards } = await Sim.getSimCards();
return simCards;
};
```
The returned `simCards` array contains carrier information for each detected SIM. On Android the list also exposes the `subscriptionId` and `simSlotIndex` values so you can correlate entries across platform APIs.
### iOS 16.4+ limitations
Starting with iOS 16.4 Apple restricts access to several carrier fields returned by CoreTelephony. On devices running iOS 16.4 or newer the plugin may return placeholder values such as `65535`, `--`, or empty strings for `carrierName`, `isoCountryCode`, `mobileCountryCode`, and `mobileNetworkCode`. This behaviour is handled at the OS level and is tracked upstream in [jonz94/capacitor-sim#8](https://github.com/jonz94/capacitor-sim/issues/8); there is currently no known workaround besides relying on Android data or older iOS versions.
## API
* [`getSimCards()`](#getsimcards)
* [`checkPermissions()`](#checkpermissions)
* [`requestPermissions()`](#requestpermissions)
* [`getPluginVersion()`](#getpluginversion)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
Capacitor SIM Plugin for retrieving information from device SIM cards.
This plugin provides access to SIM card information such as carrier name,
country code, mobile network codes, and more. Supports dual-SIM devices.
### getSimCards()
```typescript
getSimCards() => Promise
```
Get information from the device's SIM cards.
Retrieves details about all SIM cards installed in the device.
On dual-SIM devices, returns information for both SIM cards.
Requires READ_PHONE_STATE permission on Android.
**Returns:** Promise<GetSimCardsResult>
**Since:** 1.0.0
--------------------
### checkPermissions()
```typescript
checkPermissions() => Promise
```
Check permission to access SIM card information.
Checks if the app has permission to read SIM card data.
On Android, checks READ_PHONE_STATE permission.
On iOS, the status is always granted.
On Web, the status is always denied.
**Returns:** Promise<PermissionStatus>
**Since:** 1.0.0
--------------------
### requestPermissions()
```typescript
requestPermissions() => Promise
```
Request permission to access SIM card information.
Prompts the user to grant permission to read SIM card data.
On Android, requests READ_PHONE_STATE permission.
On iOS, the status is always granted without prompting.
On Web, the status remains denied.
**Returns:** Promise<PermissionStatus>
**Since:** 1.0.0
--------------------
### getPluginVersion()
```typescript
getPluginVersion() => Promise<{ version: string; }>
```
Get the native Capacitor plugin version.
**Returns:** Promise<{ version: string; }>
**Since:** 1.0.0
--------------------
### Interfaces
#### GetSimCardsResult
Result returned by {@link SimPlugin.getSimCards}.
| Prop | Type |
| -------------- | ---------------------- |
| **`simCards`** | SimCard[] |
#### SimCard
A SIM card description.
| Prop | Type | Description | Since |
| ----------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`number`** | string | Android only: Phone number for this SIM slot, when available. | 1.0.0 |
| **`subscriptionId`** | string | Android only: Unique subscription identifier. | 1.1.0 |
| **`simSlotIndex`** | number | Android only: Physical SIM slot index for this subscription. | 1.1.0 |
| **`allowsVOIP`** | boolean | iOS only: Indicates whether the carrier supports VoIP. | 1.0.0 |
| **`carrierName`** | string | Display name of the cellular service provider. On iOS 16.4+ the system may return placeholder values such as `--`. See https://github.com/jonz94/capacitor-sim/issues/8 for details. | 1.0.0 |
| **`isoCountryCode`** | string | ISO 3166-1 alpha-2 country code of the service provider. On iOS 16.4+ the system may return an empty string or `--`. See https://github.com/jonz94/capacitor-sim/issues/8 for details. | 1.0.0 |
| **`mobileCountryCode`** | string | Mobile Country Code (MCC) of the service provider. On iOS 16.4+ the system may return placeholder values such as `65535`. See https://github.com/jonz94/capacitor-sim/issues/8 for details. | 1.0.0 |
| **`mobileNetworkCode`** | string | Mobile Network Code (MNC) of the service provider. On iOS 16.4+ the system may return placeholder values such as `65535`. See https://github.com/jonz94/capacitor-sim/issues/8 for details. | 1.0.0 |
#### PermissionStatus
Result of a permission check or request.
| Prop | Type |
| ----------------- | ----------------------------------------------------------- |
| **`readSimCard`** | PermissionState |
### Type Aliases
#### PermissionState
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'