react-native-permissions

What is react-native-permissions?

The react-native-permissions package is a library for handling permissions in React Native applications. It provides a unified API to request and check permissions for various device features such as location, camera, microphone, and more.

What are react-native-permissions's main functionalities?

Requesting Permissions

This feature allows you to request specific permissions from the user. In this example, the code requests camera permission on an Android device.

import { request, PERMISSIONS } from 'react-native-permissions';

async function requestCameraPermission() {
  const result = await request(PERMISSIONS.ANDROID.CAMERA);
  console.log(result);
}

Checking Permissions

This feature allows you to check the current status of a specific permission. The example checks if the camera permission is granted on an Android device.

import { check, PERMISSIONS, RESULTS } from 'react-native-permissions';

async function checkCameraPermission() {
  const result = await check(PERMISSIONS.ANDROID.CAMERA);
  if (result === RESULTS.GRANTED) {
    console.log('Camera permission granted');
  } else {
    console.log('Camera permission not granted');
  }
}

Open App Settings

This feature allows you to open the app settings so the user can manually grant permissions. The example demonstrates how to open the app settings.

import { openSettings } from 'react-native-permissions';

function openAppSettings() {
  openSettings().catch(() => console.warn('Cannot open settings'));
}

Other packages similar to react-native-permissions

react-native-location

The react-native-location package provides location services for React Native applications. It allows you to request and check location permissions, as well as get the current location of the device. Compared to react-native-permissions, it is more focused on location-specific functionalities.

react-native-geolocation-service

The react-native-geolocation-service package is another library for handling geolocation in React Native apps. It offers more accurate and reliable location services compared to the default React Native geolocation API. While it focuses on geolocation, react-native-permissions provides a broader range of permission management.

react-native-contacts

The react-native-contacts package allows you to access and manage the device's contact list. It includes functionalities for requesting contact permissions, reading contacts, and adding new contacts. This package is specialized for contact management, whereas react-native-permissions covers a wider array of permissions.

README

☝🏼 React Native Permissions

Request user permissions on iOS and Android.

⚠️  Branch WIP 2.0.0 : Go to pull request #291 for feedbacks.

Support

version	react-native version
2.0.0+	0.56.0+
1.1.1	0.40.0 - 0.52.2

Setup

$ npm install --save react-native-permissions
# --- or ---
$ yarn add react-native-permissions

iOS specific

To allow installation of the needed permission handlers for your project (and only them), react-native-permissions uses CocoaPods. Update the following line with your path to node_modules/ and add it to your podfile:

target 'YourAwesomeProject' do

  # …

  pod 'RNPermissions', :path => '../node_modules/react-native-permissions', :subspecs => [
    'Core',
    ## Uncomment needed permissions
    # 'BluetoothPeripheral',
    # 'Calendars',
    # 'Camera',
    # 'Contacts',
    # 'FaceID',
    # 'LocationAlways',
    # 'LocationWhenInUse',
    # 'MediaLibrary',
    # 'Microphone',
    # 'Motion',
    # 'Notifications',
    # 'PhotoLibrary',
    # 'Reminders',
    # 'Siri',
    # 'SpeechRecognition',
    # 'StoreKit',
  ]

end

Android specific

• Add the following lines to android/settings.gradle:

include ':react-native-permissions'
project(':react-native-permissions').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-permissions/android')

• Add the compile line to the dependencies in android/app/build.gradle:

dependencies {
  // ...
  implementation project(':react-native-permissions')
}

• Add the import and link the package in MainApplication.java:

import com.yonahforst.rnpermissions.RNPermissionsPackage; // <-- Add the RNLocalize import

public class MainApplication extends Application implements ReactApplication {

  // …

  @Override
  protected List<ReactPackage> getPackages() {
    return Arrays.<ReactPackage>asList(
      new MainReactPackage(),
      // …
      new RNPermissionsPackage() // <-- Add it to the packages list
    );
  }

  // …
}

📌 Don't forget to add permissions to AndroidManifest.xml for android and Info.plist for iOS (Xcode >= 8).

API (subject to changes)

Permissions statuses

Promises resolve into one of these statuses:

Return value	Notes
RESULTS.UNAVAILABLE	This feature is not available on this device.
RESULTS.GRANTED	The permission is granted.
RESULTS.DENIED	The permission has not been requested / is denied but requestable.
RESULTS.NEVER_ASK_AGAIN	The permission is not requestable anymore.

Supported permissions

import { ANDROID_PERMISSIONS, IOS_PERMISSIONS } from "react-native-permissions";

// For Android

// same as PermissionsAndroid
ANDROID_PERMISSIONS.READ_CALENDAR;
ANDROID_PERMISSIONS.WRITE_CALENDAR;
ANDROID_PERMISSIONS.CAMERA;
ANDROID_PERMISSIONS.READ_CONTACTS;
ANDROID_PERMISSIONS.WRITE_CONTACTS;
ANDROID_PERMISSIONS.GET_ACCOUNTS;
ANDROID_PERMISSIONS.ACCESS_FINE_LOCATION;
ANDROID_PERMISSIONS.ACCESS_COARSE_LOCATION;
ANDROID_PERMISSIONS.RECORD_AUDIO;
ANDROID_PERMISSIONS.READ_PHONE_STATE;
ANDROID_PERMISSIONS.CALL_PHONE;
ANDROID_PERMISSIONS.READ_CALL_LOG;
ANDROID_PERMISSIONS.WRITE_CALL_LOG;
ANDROID_PERMISSIONS.ADD_VOICEMAIL;
ANDROID_PERMISSIONS.USE_SIP;
ANDROID_PERMISSIONS.PROCESS_OUTGOING_CALLS;
ANDROID_PERMISSIONS.BODY_SENSORS;
ANDROID_PERMISSIONS.SEND_SMS;
ANDROID_PERMISSIONS.RECEIVE_SMS;
ANDROID_PERMISSIONS.READ_SMS;
ANDROID_PERMISSIONS.RECEIVE_WAP_PUSH;
ANDROID_PERMISSIONS.RECEIVE_MMS;
ANDROID_PERMISSIONS.READ_EXTERNAL_STORAGE;
ANDROID_PERMISSIONS.WRITE_EXTERNAL_STORAGE;

// new ones
ANDROID_PERMISSIONS.ANSWER_PHONE_CALLS;
ANDROID_PERMISSIONS.ACCEPT_HANDOVER;
ANDROID_PERMISSIONS.READ_PHONE_NUMBERS;

// For iOS

IOS_PERMISSIONS.BLUETOOTH_PERIPHERAL;
IOS_PERMISSIONS.CALENDARS;
IOS_PERMISSIONS.CAMERA;
IOS_PERMISSIONS.CONTACTS;
IOS_PERMISSIONS.FACE_ID;
IOS_PERMISSIONS.LOCATION_ALWAYS;
IOS_PERMISSIONS.LOCATION_WHEN_IN_USE;
IOS_PERMISSIONS.MEDIA_LIBRARY;
IOS_PERMISSIONS.MICROPHONE;
IOS_PERMISSIONS.MOTION;
IOS_PERMISSIONS.NOTIFICATIONS;
IOS_PERMISSIONS.PHOTO_LIBRARY;
IOS_PERMISSIONS.REMINDERS;
IOS_PERMISSIONS.SIRI;
IOS_PERMISSIONS.SPEECH_RECOGNITION;
IOS_PERMISSIONS.STOREKIT;

Methods

types used in usage examples

type Permission =
  | keyof ANDROID_PERMISSIONS
  | keyof IOS_PERMISSIONS

type PermissionStatus =
  | "granted"
  | "denied"
  | "never_ask_again"
  | "unavailable";

type NotificationOption =
  | "badge"
  | "sound"
  | "alert"
  | "carPlay"
  | "criticalAlert"
  | "provisional";

type Rationale = {
  title: string;
  message: string;
  buttonPositive: string;
  buttonNegative?: string;
  buttonNeutral?: string;
};

check()

Check one permission status.

Method type

function check(permission: Permission): Promise<PermissionStatus>;

Usage example

import { check, IOS_PERMISSIONS, RESULTS } from "react-native-permissions";

check(RNPermissions.IOS_PERMISSIONS.LOCATION_ALWAYS).then(result => {
  switch (result) {
    case RESULTS.UNAVAILABLE:
      console.log("the feature is not available on this device");
      break;
    case RESULTS.GRANTED:
      console.log("permission is granted");
      break;
    case RESULTS.DENIED:
      console.log("permission is denied, but requestable");
      break;
    case RESULTS.NEVER_ASK_AGAIN:
      console.log("permission is denied and not requestable");
      break;
  }
});

checkMultiple()

Check multiples permissions.

Method type

function checkMultiple<P: Permission>(permissions: P[]): Promise<{ [permission: P]: PermissionStatus }>;

Usage example

import { checkMultiple, IOS_PERMISSIONS } from "react-native-permissions";

checkMultiple([
  IOS_PERMISSIONS.LOCATION_ALWAYS,
  IOS_PERMISSIONS.MEDIA_LIBRARY,
]).then(results => {
  // results.LOCATION_ALWAYS
  // results.MEDIA_LIBRARY
});

request()

Request one permission.

Method type

function request(permission: string, config: RequestConfig = {}): Promise<PermissionStatus>;

Usage example

import { request, IOS_PERMISSIONS } from "react-native-permissions";

request(IOS_PERMISSIONS.LOCATION_ALWAYS).then(result => {
  // …
});

requestMultiple()

Request multiples permissions.

Method type

function requestMultiple<P: Permission>(permissions: P[]): Promise<{ [permission: P]: PermissionStatus }>;

Usage example

import { requestMultiple, IOS_PERMISSIONS } from "react-native-permissions";

requestMultiple([
  IOS_PERMISSIONS.LOCATION_ALWAYS,
  IOS_PERMISSIONS.MEDIA_LIBRARY,
]).then(results => {
  // results.LOCATION_ALWAYS
  // results.MEDIA_LIBRARY
});

openSettings()

Open application settings.

Method type

function openSettings(): Promise<boolean>;

Usage example

import { openSettings } from "react-native-permissions";

openSettings().catch(() => console.warn("cannot open settings");

🍎  iOS Notes

• Permission type BLUETOOTH_PERIPHERAL represents the status of the CBPeripheralManager.
• If notificationOptions config array is omitted on NOTIFICATIONS request, it will request alert, badge and sound.