Capacitor plugin for reading SIM card and carrier information.
- 📇 SIM cards: Read information about the SIM cards installed on the device.
- 🔀 Multi-SIM: Supports devices with multiple SIM slots.
- 🌐 Carrier details: Read carrier name, country code, MCC and MNC.
- 🔒 Permissions: Built-in handling of the required runtime permission.
- 🤝 Compatibility: Works alongside the Device Info, Network and Phone Dialer plugins.
- 🔁 Up-to-date: Always supports the latest Capacitor version.
Missing a feature? Just open an issue and we'll take a look!
The SIM plugin is typically used when an app needs to know about the device's SIM cards or carrier, for example:
- Carrier-specific features: Enable or disable functionality depending on the carrier name or the MCC and MNC of the SIM card.
- Country detection: Use the SIM card's ISO country code to preselect a country or region in your app.
- Multi-SIM handling: Show which SIM slots are in use on devices with multiple SIM slots.
- eSIM detection: Detect whether a SIM card is an embedded SIM (eSIM).
| Plugin Version | Capacitor Version | Status |
|---|---|---|
| 0.x.x | >=8.x.x | Active support |
You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:
npx skills add capawesome-team/skills --skill capacitor-pluginsThen use the following prompt:
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/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:
npm install @capawesome/capacitor-sim
npx cap syncThis plugin is only available on Android. On iOS and Web, all methods reject as unimplemented (see iOS below).
The READ_PHONE_STATE permission is declared in the plugin's AndroidManifest.xml and is merged into your app automatically. You must request it at runtime via the requestPermissions(...) method before calling getSimCards(...).
Reading SIM card and carrier information is not supported on iOS. Apple deprecated the CTCarrier APIs of the Core Telephony framework with iOS 16, and they return placeholder values (e.g. "--" and 65535) on iOS 16.4 and later. Because there is no reliable system API left, all methods reject as unimplemented on iOS.
No configuration required for this plugin.
The following examples show how to check and request permissions and read the SIM cards installed on the device.
Reading the SIM cards requires the READ_PHONE_STATE runtime permission on Android. Check the current permission state and request the permission before calling getSimCards(...). Only available on Android:
import { Sim } from '@capawesome/capacitor-sim';
const checkPermissions = async () => {
const { readSimCards } = await Sim.checkPermissions();
return readSimCards;
};
const requestPermissions = async () => {
const { readSimCards } = await Sim.requestPermissions();
return readSimCards;
};Get information about the SIM cards installed on the device, such as the carrier name, country code, MCC and MNC. On devices with multiple SIM slots, all active SIM cards are returned. Only available on Android:
import { Sim } from '@capawesome/capacitor-sim';
const getSimCards = async () => {
const { simCards } = await Sim.getSimCards();
return simCards;
};checkPermissions() => Promise<PermissionStatus>Check the permission to read the SIM cards.
Only available on Android.
Returns: Promise<PermissionStatus>
Since: 0.1.0
getSimCards() => Promise<GetSimCardsResult>Get information about the SIM cards installed on the device.
On devices with multiple SIM slots, all active SIM cards are returned.
Only available on Android.
Returns: Promise<GetSimCardsResult>
Since: 0.1.0
requestPermissions() => Promise<PermissionStatus>Request the permission to read the SIM cards.
Only available on Android.
Returns: Promise<PermissionStatus>
Since: 0.1.0
| Prop | Type | Description | Since |
|---|---|---|---|
readSimCards |
PermissionState |
The permission state of reading the SIM cards. | 0.1.0 |
| Prop | Type | Description | Since |
|---|---|---|---|
simCards |
SimCard[] |
The SIM cards installed on the device. | 0.1.0 |
| Prop | Type | Description | Since |
|---|---|---|---|
carrierName |
string | null |
The name of the carrier. Returns null if the carrier name is not available. |
0.1.0 |
displayName |
string | null |
The user-editable display name of the SIM card. Returns null if the display name is not available. |
0.1.0 |
isEmbedded |
boolean | null |
Whether the SIM card is an embedded SIM (eSIM). Returns null if the information is not available. |
0.1.0 |
isoCountryCode |
string | null |
The two-letter ISO 3166-1 country code of the carrier. Returns null if the country code is not available. |
0.1.0 |
mobileCountryCode |
string | null |
The Mobile Country Code (MCC) of the carrier. Returns null if the mobile country code is not available. |
0.1.0 |
mobileNetworkCode |
string | null |
The Mobile Network Code (MNC) of the carrier. Returns null if the mobile network code is not available. |
0.1.0 |
phoneNumber |
string | null |
The phone number associated with the SIM card. This value is often empty because carriers do not reliably store the phone number on the SIM card. In that case, null is returned. |
0.1.0 |
slotIndex |
number |
The index of the SIM slot on the device. | 0.1.0 |
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
It reads the full picture of the device's SIM cards in a single call — carrier name, ISO country code, MCC and MNC, eSIM status, and the slot index for every active card on multi-SIM devices — through a fully typed API that handles the required Android runtime permission for you. It's honest about platform reality, too: SIM data is well supported on Android, while iOS no longer exposes it reliably, so the plugin focuses where the information is actually available. If you only need a rough country hint, a lighter approach may be enough; if you need dependable multi-SIM and carrier details, this plugin is built for exactly that.
Apple deprecated the CTCarrier APIs of the Core Telephony framework with iOS 16, and they return placeholder values (e.g. "--" and 65535) on iOS 16.4 and later. Because there is no reliable system API left for reading SIM card and carrier information, all methods reject as unimplemented on iOS. See the iOS installation notes for details.
The plugin requires the READ_PHONE_STATE permission on Android. It is declared in the plugin's AndroidManifest.xml and merged into your app automatically, so no manual manifest changes are needed. However, you must request the permission at runtime via the requestPermissions method before calling getSimCards.
The phoneNumber property is often empty because carriers do not reliably store the phone number on the SIM card. In that case, the plugin returns null. Other properties such as carrierName or isoCountryCode may also be null if the information is not available.
Yes, on devices with multiple SIM slots, the getSimCards method returns all active SIM cards. Each SIM card includes a slotIndex property that indicates the index of the SIM slot on the device.
Yes, each SIM card includes an isEmbedded property that indicates whether it is an embedded SIM (eSIM). The property returns null if the information is not available.
Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.
- Device Info: Read device information, such as the model, manufacturer, and operating system.
- Network: Access network information.
- Phone Dialer: Open the native phone dialer prefilled with a phone number.
Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.
See CHANGELOG.md.
See LICENSE.