Expo Docs MCP Server

--- title: Location description: A library that provides access to reading geolocation information, polling current location or subscribing location update events from the device. sourceCodeUrl: https://github.com/expo/expo/tree/sdk-51/packages/expo-location packageName: expo-location iconUrl: /static/images/packages/expo-location.png platforms: ["android", "ios", "web"] --- import { ConfigReactNative, ConfigPluginExample, ConfigPluginProperties, } from '~/ui/components/ConfigSection'; `expo-location` allows reading geolocation information from the device. Your app can poll for the current location or subscribe to location update events. ## Installation ## Configuration in app config You can configure `expo-location` using its built-in [config plugin](/config-plugins/introduction/) if you use config plugins in your project ([EAS Build](/build/introduction) or `npx expo run:[android|ios]`). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. ```json app.json { "expo": { "plugins": [ [ "expo-location", { "locationAlwaysAndWhenInUsePermission": "Allow $(PRODUCT_NAME) to use your location." } ] ] } } ``` If you're not using Continuous Native Generation ([CNG](/workflow/continuous-native-generation/)) or you're using native **ios** project manually, then you need to add the `NSLocationAlwaysAndWhenInUseUsageDescription`, `NSLocationAlwaysUsageDescription` and `NSLocationWhenInUseUsageDescription` keys to your project's **ios/[app]/Info.plist**: ```xml <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 methods > **warning** **Warning:** Background location tracking support is provided as-is and is not guaranteed to work in all scenarios. We currently are not prioritizing resources to improve it, but we hope to in the future. You may want to use [`react-native-background-geolocation`](https://github.com/transistorsoft/react-native-background-geolocation) instead &mdash; it requires purchasing a license and is a well-maintained and supported library that includes a config plugin. To use Background Location methods, the following requirements apply: - Location permissions must be granted. On iOS it must be granted with `Always` option. - Background location task must be defined in the top-level scope, using [`TaskManager.defineTask`](task-manager.md#taskmanagerdefinetasktaskname-taskexecutor). - `"location"` background mode must be specified in **Info.plist** file. See [background tasks configuration guide](./task-manager.md#configuration-in-appjsonappconfigjs). ### Geofencing methods To use Geofencing methods, the following requirements apply: - Location permissions must be granted. On iOS it must be granted with `Always` option. - The Geofencing task must be defined in the top-level scope, using [`TaskManager.defineTask`](task-manager.md#taskmanagerdefinetasktaskname-taskexecutor). - On iOS, there is a [limit of 20](https://developer.apple.com/documentation/corelocation/monitoring_the_user_s_proximity_to_geographic_regions) `regions` that can be simultaneously monitored. ## Usage If you're using the Android Emulator or iOS Simulator, ensure that [Location is enabled](#enable-emulator-location). ```jsx /* @hide */ /* @end */ const [location, setLocation] = useState(null); const [errorMsg, setErrorMsg] = useState(null); useEffect(() => { (async () => { /* @hide */ if (Platform.OS === 'android' && !Device.isDevice) { setErrorMsg( 'Oops, this will not work on Snack in an Android Emulator. Try it on your device!' ); return; } /* @end */ let { status } = await Location.requestForegroundPermissionsAsync(); if (status !== 'granted') { setErrorMsg('Permission to access location was denied'); return; } let location = await Location.getCurrentPositionAsync({}); setLocation(location); })(); }, []); 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 ```js ``` ## Permissions ### Android > **Note:** Foreground and background services are not available in Expo Go for Android. 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](https://support.google.com/googleplay/android-developer/answer/13392821?hl=en). - `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](https://support.google.com/googleplay/android-developer/answer/9799150?hl=en). #### 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](#accuracy). 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](#low), you can exclude `ACCESS_FINE_LOCATION` permission. To learn more about levels of location accuracies, see [Android documentation](https://developer.android.com/training/location/permissions#accuracy). To learn more on how to exclude permission, see [Excluding Android permissions](/guides/permissions/#excluding-android-permissions). ### iOS The following usage description keys are used by this library: