Capacitor SIM Plugin

Capacitor plugin for reading SIM card and carrier information.

Features

• 📇 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.
• 🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

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).

Compatibility

| Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | >=8.x.x | Active support |

Installation

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-plugins

Then 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 sync

This plugin is only available on Android. On iOS and Web, all methods reject as unimplemented (see iOS below).

Android

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(...).

iOS

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.

Configuration

No configuration required for this plugin.

Usage

The following examples show how to check and request permissions and read the SIM cards installed on the device.

Check and request permissions

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;
};

Read the SIM cards

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;
};

API

• checkPermissions()
• getSimCards()
• requestPermissions()
• Interfaces
• Type Aliases

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check the permission to read the SIM cards.

Only available on Android.

Returns: Promise<PermissionStatus>

Since: 0.1.0

getSimCards()

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()

requestPermissions() => Promise<PermissionStatus>

Request the permission to read the SIM cards.

Only available on Android.

Returns: Promise<PermissionStatus>

Since: 0.1.0

Interfaces

PermissionStatus

| Prop | Type | Description | Since | | ------------------ | ----------------------------------------------------------- | ---------------------------------------------- | ----- | | readSimCards | PermissionState | The permission state of reading the SIM cards. | 0.1.0 |

GetSimCardsResult

| Prop | Type | Description | Since | | -------------- | ---------------------- | -------------------------------------- | ----- | | simCards | SimCard[] | The SIM cards installed on the device. | 0.1.0 |

SimCard

| 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 |

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

FAQ

How is this plugin different from other similar plugins?

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.

Why is the SIM plugin not available 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 for reading SIM card and carrier information, all methods reject as unimplemented on iOS. See the iOS installation notes for details.

Which permissions are required to read the SIM cards?

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.

Why is the phone number null?

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.

Does the plugin support dual-SIM devices?

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.

Can I detect whether a SIM card is an eSIM?

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.

Can I use this plugin with Ionic, React, Vue or Angular?

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.

Related Plugins

• 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.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.