This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

expo-location allows reading geolocation information from the device. Your app can poll for the current location or subscribe to location update events.

Installation

If you are installing this in an existing React Native app, make sure to install expo in your project.

Configuration in app config

You can configure expo-location using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.

Example app.json with config plugin

{
  "expo": {
    "plugins": [
      [
        "expo-location",
        {
          "locationAlwaysAndWhenInUsePermission": "Allow $(PRODUCT_NAME) to use your location."
        }
      ]
    ]
  }
}

Configurable properties

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to use your location</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to use your location</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to use your location</string>

Background location

Background location allows your app to receive location updates while it is running in the background and includes both location updates and region monitoring through geofencing. This feature is subject to platform API limitations and system constraints:

• Background location will stop if the user terminates the app.
• Background location resumes if the user restarts the app.
• Android
  A terminated app will not automatically restart when a location or geofencing event occurs due to platform limitations.
• iOS
  The system will restart the terminated app when a new geofence event occurs.

On Android, the result of removing an app from the recent apps list varies by device vendor. For example, some implementations treat removing an app from the recent apps list as killing it. Read more about these differences here: https://dontkillmyapp.com.

Background location configuration 

iOS

To be able to run background location on iOS, you need to add the location value to the UIBackgroundModes array in your app's Info.plist file.

If you're using CNG, the required UIBackgroundModes configuration will be applied automatically by prebuild.

<key>UIBackgroundModes</key>
  <array>
    <string>location</string>
  </array>

Background location methods

To use Background Location methods, the following requirements apply:

• Location permissions must be granted.
• Background location task must be defined in the top-level scope, using TaskManager.defineTask.
• iOS
  "location" background mode must be specified in Info.plist file. See Background location configuration.
• iOS
  You must use a development build to use background location since it is not supported in the Expo Go app.

Geofencing methods

To use Geofencing methods, the following requirements apply:

• Location permissions must be granted.
• The Geofencing task must be defined in the top-level scope, using TaskManager.defineTask.

When using Geofencing, the following platform differences apply:

• Android
  You are allowed up to 100 active geofences per app.
• iOS
  Expo Location will report the initial state of the registered geofence(s) at app startup.
• iOS
  There is a limit of 20 regions that can be simultaneously monitored.

Background permissions

To use location tracking or Geofencing in the background, you must request the appropriate permissions:

• On Android, you must request both foreground and background permissions.
• On iOS, it must be granted with the Always option using requestBackgroundPermissionsAsync.

import { Linking } from 'react-native';

function openSettings() {
  Linking.openURL('app-settings:');
}

Deferred locations

When using background locations, you can configure the location manager to defer updates. This helps save battery by reducing update frequency. You can set updates to trigger only after the device has moved a certain distance or after a specified time interval.

Deferred updates are configured through LocationTaskOptions using the deferredUpdatesDistance, deferredUpdatesInterval and deferredTimeout properties.

Deferred locations apply only when the app is in the background.

Usage

If you're using the Android Emulator or iOS Simulator, ensure that Location is enabled.

import { useState, useEffect } from 'react';
import { Platform, Text, View, StyleSheet } from 'react-native';
%%placeholder-start%%%%placeholder-end%%import * as Device from 'expo-device';
import * as Location from 'expo-location';

export default function App() {
  const [location, setLocation] = useState<Location.LocationObject | null>(null);
  const [errorMsg, setErrorMsg] = useState<string | null>(null);

  useEffect(() => {
    async function getCurrentLocation() {
      %%placeholder-start%%%%placeholder-end%%if (Platform.OS === 'android' && !Device.isDevice) {
        setErrorMsg(
          'Oops, this will not work on Snack in an Android Emulator. Try it on your device!'
        );
        return;
      }
      let { status } = await Location.requestForegroundPermissionsAsync();
      if (status !== 'granted') {
        setErrorMsg('Permission to access location was denied');
        return;
      }

      let location = await Location.getCurrentPositionAsync({});
      setLocation(location);
    }

    getCurrentLocation();
  }, []);

  let text = 'Waiting...';
  if (errorMsg) {
    text = errorMsg;
  } else if (location) {
    text = JSON.stringify(location);
  }

  return (
    <View style={styles.container}>
      <Text style={styles.paragraph}>{text}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
    padding: 20,
  },
  paragraph: {
    fontSize: 18,
    textAlign: 'center',
  },
});

Enable emulator location

Android Emulator

Open Android Studio, and launch the Android Emulator. Inside it, go to Settings > Location and enable Use location.

If you don't receive the locations in the emulator, you may have to turn off the Improve Location Accuracy setting. This will turn off Wi-Fi location and only use GPS. Then you can manipulate the location with GPS data through the emulator.

For Android 12 and higher, go to Settings > Location > Location Services > Google Location Accuracy, and turn off Improve Location Accuracy. For Android 11 and lower, go to Settings > Location > Advanced > Google Location Accuracy, and turn off Google Location Accuracy.

iOS Simulator

With Simulator open, go to Features > Location and choose any option besides None.

API

import * as Location from 'expo-location';

Hooks

const [status, requestPermission] = Location.useBackgroundPermissions();

const [status, requestPermission] = Location.useForegroundPermissions();

Methods

import { GeofencingEventType } from 'expo-location';
import * as TaskManager from 'expo-task-manager';

 TaskManager.defineTask(YOUR_TASK_NAME, ({ data: { eventType, region }, error }) => {
  if (error) {
    // check `error.message` for more details.
    return;
  }
  if (eventType === GeofencingEventType.Enter) {
    console.log("You've entered region:", region);
  } else if (eventType === GeofencingEventType.Exit) {
    console.log("You've left region:", region);
  }
});

import * as TaskManager from 'expo-task-manager';

TaskManager.defineTask(YOUR_TASK_NAME, ({ data: { locations }, error }) => {
 if (error) {
   // check `error.message` for more details.
   return;
 }
 console.log('Received new locations', locations);
});

Types

Enums

Permissions

Android

Foreground and background services are not available in Expo Go for Android. Instead, we recommend using a development build to avoid limitations.

When you install the expo-location module, it automatically adds the following permissions:

• ACCESS_COARSE_LOCATION: for approximate device location
• ACCESS_FINE_LOCATION: for precise device location

The following permissions are optional:

• FOREGROUND_SERVICE and FOREGROUND_SERVICE_LOCATION: to be able to access location while the app is open but backgrounded. FOREGROUND_SERVICE_LOCATION is only required as of Android 14. When you enable this in a new build, you will need to submit your app for review and request access to use the foreground service permission.
• ACCESS_BACKGROUND_LOCATION: to be able to access location while the app is backgrounded or closed. When you enable this in a new build, you will need to submit your app for review and request access to use the background location permission.

Excluding a permission

Note: Excluding a required permission from a module in your app can break the functionality corresponding to that permission. Always make sure to include all permissions a module is dependent on.

When your Expo project doesn't benefit from having particular permission included, you can omit it. For example, if your application doesn't need access to the precise location, you can exclude the ACCESS_FINE_LOCATION permission.

Another example can be stated using available location accuracies. Android defines the approximate location accuracy estimation within about 3 square kilometers, and the precise location accuracy estimation within about 50 meters. For example, if the location accuracy value is Low, you can exclude ACCESS_FINE_LOCATION permission. To learn more about levels of location accuracies, see Android documentation.

To learn more on how to exclude permission, see Excluding Android permissions.

iOS

The following usage description keys are used by this library:

NSLocationAlwaysUsageDescription is deprecated in favor of NSLocationAlwaysAndWhenInUseUsageDescription from iOS 11.