Permissions

Installation

Permissions on iOS

Note: apps using permissions without descriptions may be rejected from the App Store. (see the App Store Deployment Guide)

Permissions on Android

Some Expo and React Native modules include permissions by default. If you use expo-location, for example, both the ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION are implied and added to your app's permissions automatically.

Note: see the android.permissions documentation to learn about which permissions are always included.

Note: apps using dangerous or signature permissions without valid reasons may be rejected by Google. Make sure you follow the Android permissions best practices when submitting your app.

Note: by default, the permissions implied by the modules you installed are added to the AndroidManifest.xml. To exclude permissions, you have to define the android.permissions manifest property or blacklist them in the bare workflow.

Permissions on Web

Usage

Manually testing permissions

Permissions and required packages on iOS

Excluding Android permissions in bare workflow

<manifest xmlns:tools="http://schemas.android.com/tools">
  <uses-permission tools:node="remove" android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

Note: you have to define the xmlns:tools attribute on <manifest> before you can use the tools:node attribute on permissions.

API

import * as Permissions from 'expo-permissions';

Hooks

usePermissions

const [permission, askPermission, getPermission] = usePermissions(Permissions.CAMERA, { ... });

Arguments

• permissionTypes (Type|Type[]) -- One or more types to get or ask permission for. After the permission status is fetched, you can show different UI based on the current status.
• permissionOptions -- Optional configuration to change the behavior of the hook.
  • get (boolean) -- Retrieves the permission status without interacting with the user, true by default.
  • ask (boolean) -- Prompts the user with the requested permission directly. Without using the askPermission callback, false by default.

Returns

• permission (PermissionsResponse|undefined) -- An object with information about the permissions, including status, expiration, and scope (if applicable).
• askPermission (() => void) -- A callback to ask the user for permission.
• getPermission (() => void) -- A callback to get the permission status without interacting with the user.

Example: hook

function App() {
  const [permission, askForPermission] = usePermissions(Permissions.CAMERA, { ask: true });

  if (!permission || permission.status !== 'granted') {
    return (
      <View>
        <Text>Permission is not granted</Text>
        <Button title="Grant permission" onPress={askForPermission} />
      </View>
    );
  }

  return (
    <View>
      <Camera />
    </View>
  );
}

Permissions.getAsync(...types)

Arguments

• permissionTypes (string) -- The names of the permissions types.

Returns

Example

async function alertIfRemoteNotificationsDisabledAsync() {
  const { status } = await Permissions.getAsync(Permissions.NOTIFICATIONS);
  if (status !== 'granted') {
    alert('Hey! You might want to enable notifications for my app, they are good.');
  }
}

async function checkMultiPermissions() {
  const { status, expires, permissions } = await Permissions.getAsync(
    Permissions.CALENDAR,
    Permissions.CONTACTS
  );
  if (status !== 'granted') {
    alert('Hey! You have not enabled selected permissions');
  }
}

Permissions.askAsync(...types)

Arguments

• types (string) -- The names of the permissions types.

Returns

Example

async function getLocationAsync() {
  // permissions returns only for location permissions on iOS and under certain conditions, see Permissions.LOCATION
  const { status, permissions } = await Permissions.askAsync(Permissions.LOCATION);
  if (status === 'granted') {
    return Location.getCurrentPositionAsync({ enableHighAccuracy: true });
  } else {
    throw new Error('Location permission not granted');
  }
}

Types

PermissionResponse

interface PermissionResponse {
  status: 'granted' | 'undetermined' | 'denied';
  granted: boolean;
  expires: 'never' | number;
  canAskAgain: boolean;
  permissions: {
    // an object with an entry for each permission requested
    [permissionType: string /* PermissionType */]: PermissionInfo;
  };
}

PermissionResponse.status

• When one or more permissions are undetermined, the status is undetermined
• When one or more permissions are denied, but none of them are undetermined, the status is denied
• When all permissions are granted, the status is granted.

[granted, granted, granted] => granted
[granted, granted, denied] => denied
[denied, denied, denied] => denied
[granted, granted, undetermined] => undetermined
[granted, denied, undetermined] => undetermined

PermissionResponse.granted

PermissionResponse.expires

PermissionResponse.canAskAgain

PermissionResponse.permissions

PermissionInfo

interface PermissionInfo {
  status: 'granted' | 'undetermined' | 'denied';
  granted: boolean;
  expires: 'never' | number;
  canAskAgain: boolean;
  ios?: {
    scope: 'whenInUse' | 'always';
  };
  android?: {
    scope: 'fine' | 'coarse' | 'none';
  };
}

Permission types

• Permissions.NOTIFICATIONS -- user-facing notifications and remote push notifications
• Permissions.USER_FACING_NOTIFICATIONS -- only user-facing notifications
• Permissions.LOCATION -- accessing the location of the user
• Permissions.CAMERA -- using the camera to capture images or videos
• Permissions.AUDIO_RECORDING -- using the microphone to capture audio
• Permissions.CONTACTS -- reading or writing to contacts
• Permissions.MEDIA_LIBRARY_WRITE_ONLY -- writing to media library
• Permissions.MEDIA_LIBRARY -- accessing the images or videos from the user
• Permissions.CALENDAR -- reading or writing calendar items
• Permissions.REMINDERS -- reading or writing calendar reminders (iOS-only)
• Permissions.SYSTEM_BRIGHTNESS -- changing brightness of the screen system-wide
• Permissions.MOTION -- device orientation and device motion (web-only)

Permissions.NOTIFICATIONS

• Android: it doesn't require any permissions in your manifest.
• iOS: it requires the expo-notifications module and doesn't require a message.

Note (iOS): Asking for this permission asks the user not only for permission to register for push/remote notifications, but also for showing notifications as such. At the moment remote notifications will only be received when notifications are permitted to play a sound, change the app badge or be displayed as an alert. As iOS is more detailed when it comes to notifications permissions, this permission status will contain not only status and expires, but also Boolean values for allowsSound, allowsAlert and allowsBadge.

Note (iOS): This does not disambiguate undetermined from denied and so will only ever return granted or undetermined. This is due to the way the underlying native API is implemented. On iOS simulators, since they don't support registering for push notifications, you will always get undetermined result.

Note (Android): Android does not differentiate between permissions for local and remote notifications, so status of permission for NOTIFICATIONS should always be the same as the status for USER_FACING_NOTIFICATIONS.

Permissions.USER_FACING_NOTIFICATIONS

• Android: this permission is the same as NOTIFICATIONS and returns the status from that permission.
• iOS: it requires the expo-notifications module and doesn't require a message.

Note (iOS): It provides more detailed permissions, so the permission status will contain not only status and expires, but also Boolean values for allowsSound, allowsAlert and allowsBadge.

Permissions.LOCATION

• Android: it requires the ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION permissions in your manifest.
• iOS: it requires the expo-location module and one of the messages below.

Note (iOS): This is not working with this permission being not individually, Permissions.askAsync(Permissions.SOME_PERMISSIONS, Permissions.LOCATION, Permissions.CAMERA, ...) would throw. On iOS ask for this permission type individually.

Note (iOS): In Expo client on iOS this permission will always ask the user for permission to access location data while the app is in use.

If you would like to access location data in a standalone app, note that you'll need to provide location usage descriptions in app.json. For more information see Deploying to App Stores guide.

scope

What location usage descriptions should I provide on iOS?

• if you provide only NSLocationWhenInUseUsageDescription, your application will only ever ask for location access permission "when in use",
• if you provide both NSLocationWhenInUseUsageDescription and NSLocationAlwaysAndWhenInUseUsageDescription, your application will only ask for "when in use" permission on iOS 10, whereas on iOS 11+ it will show a dialog to the user where he'll be able to pick whether he'd like to give your app permission to access location always or only when the app is in use,
• if you provide all three: NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription and NSLocationAlwaysUsageDescription, your application on iOS 11+ will still show a dialog described above and on iOS 10 it will only ask for "always" location permission.

Permissions.CAMERA

• Android: it requires the CAMERA permission in your manifest.
• iOS: it requires any of the modules listed below and NSCameraUsageDescription message

Note (iOS): You can request this permission with the expo-barcode-scanner, expo-camera, expo-face-detector, expo-image-picker, or expo-media-library module.

Permissions.AUDIO_RECORDING

• Android: it requires the RECORD_AUDIO permission in your manifest.
• iOS: it requires the expo-av module and NSMicrophoneUsageDescription message.

Permissions.CONTACTS

• Android: it requires the READ_CONTACTS and (optionally) WRITE_CONTACTS in your manifest.
• iOS: it requires the expo-contacts module and NSContactsUsageDescription message.

Permissions.MEDIA_LIBRARY_WRITE_ONLY

• Android: it requires the WRITE_EXTERNAL_STORAGE permissions in your manifest.
• iOS it requires the expo-image-picker or expo-media-library module and NSPhotoLibraryAddUsageDescription message.

Permissions.MEDIA_LIBRARY

• Android: it requires the READ_EXTERNAL_STORAGE and WRITE_EXTERNAL_STORAGE permissions in your manifest.
• iOS it requires the expo-image-picker or expo-media-library module and NSPhotoLibraryUsageDescription message.

Note (iOS): iOS provides more detailed permissions, returning { status, permissions: { cameraRoll: { accessPrivileges } } } where accessPrivileges can be:

• all if the user granted your app access to the whole photo library
• limited if the user granted your app access only to selected photos (only available on iOS 14.0+)
• none if user denied or hasn't yet granted the permission

Permissions.CALENDAR

• Android: it requires the READ_CALENDAR and WRITE_CALENDAR permissions in your manifest.
• iOS: it requires the expo-calendar module and NSCalendarsUsageDescription message.

Permissions.REMINDERS

• Android: this permission has no effect on Android and is resolved as granted immediately.
• iOS: it requires the expo-calendar module and NSRemindersUsageDescription message.

Permissions.SYSTEM_BRIGHTNESS

• Android: it requires the WRITE_SETTINGS permission in your manifest.
• iOS: this permission has no effect on iOS and is resolved as granted immediately.

Permissions.MOTION