An API that provides information about the user's cellular service provider.
expo-cellular
provides information about the user's cellular service provider, such as its unique identifier, cellular connection type, and whether it allows VoIP calls on its network.
-
npx expo install expo-cellular
If you are installing this in an existing React Native app, start by installing expo
in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.
Learn how to configure the native projects in the installation instructions in the expo-cellular
repository.
import * as Cellular from 'expo-cellular';
Deprecated Use
allowsVoipAsync()
instead.
Cellular.allowsVoip
Type: boolean | null
Indicates if the carrier allows making VoIP calls on its network. On Android, this checks whether the system supports SIP-based VoIP API. See the Android documentation for more information.
On iOS, if you configure a device for a carrier and then remove the SIM card, this property
retains the boolean
value indicating the carrier’s policy regarding VoIP. If you then install
a new SIM card, its VoIP policy boolean
replaces the previous value of this property.
On web, this returns null
.
Example
Cellular.allowsVoip; // true or false
Deprecated Use
getCarrierNameAsync()
instead.
Cellular.carrier
Type: string | null
The name of the user’s home cellular service provider. If the device has dual SIM cards, only the
carrier for the currently active SIM card will be returned. On Android, this value is only
available when the SIM state is SIM_STATE_READY
.
Otherwise, this returns null
.
On iOS, if you configure a device for a carrier and then remove the SIM card, this property
retains the name of the carrier. If you then install a new SIM card, its carrier name replaces
the previous value of this property. The value for this property is null
if the user never
configured a carrier for the device.
On web, this returns null
.
Example
Cellular.carrier; // "T-Mobile" or "Verizon"
Deprecated Use
getIsoCountryCodeAsync()
instead.
Cellular.isoCountryCode
Type: string | null
The ISO country code for the user’s cellular service provider. On iOS, the value is null
if any
of the following apply:
On web, this returns null
.
Example
Cellular.isoCountryCode; // "us" or "au"
Deprecated Use
getMobileCountryCodeAsync()
instead.
Cellular.mobileCountryCode
Type: string | null
The mobile country code (MCC) for the user’s current registered cellular service provider.
On Android, this value is only available when SIM state is SIM_STATE_READY
. Otherwise, this
returns null
. On iOS, the value may be null on hardware prior to iPhone 4S when in airplane mode.
Furthermore, the value for this property is null
if any of the following apply:
On web, this returns null
.
Example
Cellular.mobileCountryCode; // "310"
Deprecated Use
getMobileNetworkCodeAsync()
instead.
Cellular.mobileNetworkCode
Type: string | null
The ISO country code for the user’s cellular service provider. On iOS, the value is null
if
any of the following apply:
On web, this returns null
.
Example
Cellular.mobileNetworkCode; // "260"
usePermissions(options)
Parameter | Type |
---|---|
options (optional) | PermissionHookOptions<object> |
Check or request permissions to access the phone state.
This uses both Cellular.requestPermissionsAsync
and Cellular.getPermissionsAsync
to interact with the permissions.
[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]
Example
const [status, requestPermission] = Cellular.usePermissions();
Cellular.allowsVoipAsync()
Promise<boolean | null>
Returns if the carrier allows making VoIP calls on its network. On Android, this checks whether the system supports SIP-based VoIP API. See here to view more information.
On iOS, if you configure a device for a carrier and then remove the SIM card, this property
retains the boolean
value indicating the carrier’s policy regarding VoIP. If you then install
a new SIM card, its VoIP policy boolean
replaces the previous value of this property.
On web, this returns null
.
Example
await Cellular.allowsVoipAsync(); // true or false
Cellular.getCarrierNameAsync()
Promise<string | null>
Returns name of the user’s home cellular service provider. If the device has dual SIM cards, only the carrier for the currently active SIM card will be returned.
On Android, this value is only available when the SIM state is SIM_STATE_READY
.
Otherwise, this returns null
.
On iOS, if you configure a device for a carrier and then remove the SIM card, this property
retains the name of the carrier. If you then install a new SIM card, its carrier name replaces
the previous value of this property. The value for this property is null
if the user never
configured a carrier for the device.
On web, this returns null
.
Example
await Cellular.getCarrierNameAsync(); // "T-Mobile" or "Verizon"
Cellular.getCellularGenerationAsync()
Returns a promise which fulfils with a Cellular.CellularGeneration
enum value that represents the current cellular-generation type.
You will need to check if the native permission has been accepted to obtain generation.
If the permission is denied getCellularGenerationAsync
will resolve to Cellular.Cellular Generation.UNKNOWN
.
On web, this method uses navigator.connection.effectiveType
to detect the effective type of the connection using a combination of recently observed
round-trip time and downlink values. See here
to view browser compatibility.
Example
await Cellular.getCellularGenerationAsync();
// CellularGeneration.CELLULAR_4G
Cellular.getIsoCountryCodeAsync()
Promise<string | null>
Returns the ISO country code for the user’s cellular service provider.
On iOS, the value is null
if any of the following apply:
On web, this returns null
.
Example
await Cellular.getIsoCountryCodeAsync(); // "us" or "au"
Cellular.getMobileCountryCodeAsync()
Promise<string | null>
Returns mobile country code (MCC) for the user’s current registered cellular service provider.
On Android, this value is only available when SIM state is SIM_STATE_READY
. Otherwise, this
returns null
. On iOS, the value may be null on hardware prior to iPhone 4S when in airplane mode.
Furthermore, the value for this property is null
if any of the following apply:
On web, this returns null
.
Example
await Cellular.getMobileCountryCodeAsync(); // "310"
Cellular.getMobileNetworkCodeAsync()
Promise<string | null>
Returns the mobile network code (MNC) for the user’s current registered cellular service provider.
On Android, this value is only available when SIM state is SIM_STATE_READY
. Otherwise, this
returns null
. On iOS, the value may be null on hardware prior to iPhone 4S when in airplane mode.
Furthermore, the value for this property is null
if any of the following apply:
On web, this returns null
.
Example
await Cellular.getMobileNetworkCodeAsync(); // "310"
Cellular.requestPermissionsAsync()
Asks the user to grant permissions for accessing the phone state.
CellularGeneration
Describes the current generation of the cellular connection. It is an enum with these possible values:
CellularGeneration Values
UNKNOWN
CellularGeneration.UNKNOWN = 0
Either we are not currently connected to a cellular network or type could not be determined.
CELLULAR_2G
CellularGeneration.CELLULAR_2G = 1
Currently connected to a 2G cellular network. Includes CDMA, EDGE, GPRS, and IDEN type connections.
CELLULAR_3G
CellularGeneration.CELLULAR_3G = 2
Currently connected to a 3G cellular network. Includes EHRPD, EVDO, HSPA, HSUPA, HSDPA, HSPAP, and UTMS type connections.
CELLULAR_4G
CellularGeneration.CELLULAR_4G = 3
Currently connected to a 4G cellular network. Includes LTE type connections.
CELLULAR_5G
CellularGeneration.CELLULAR_5G = 4
Currently connected to a 5G cellular network. Includes NR and NRNSA type connections.
Code | Description |
---|---|
ERR_CELLULAR_GENERATION_UNKNOWN_NETWORK_TYPE | Unable to access network type or not connected to a cellular network |
You must add the following permissions to your app.json inside the expo.android.permissions
array.
Android Permission | Description |
---|---|
Allows read only access to phone state, including the current cellular network information, the status of any ongoing calls, and a list of any PhoneAccounts registered on the device.
|
No permissions required.