Expo Location (next)

By default, a permission request asks for the precise location. On Android, this requests both ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION; when the user has already granted the approximate location, the dialog asks to change it to the precise one. On iOS, when the user has turned Precise Location off for the app, the request also shows the system prompt for temporary full accuracy.

import { Location, LocationAccuracy } from 'expo-location/next';

async function requestPreciseLocation() {
  const { granted, accuracy } = await Location.requestForegroundPermissions();
  if (!granted) {
    return;
  }
  if (accuracy === LocationAccuracy.REDUCED) {
    // The user declined precise location. Positions are accurate to kilometers, not meters.
  }
  const position = await Location.getPosition();
  if (!position) {
    return;
  }
  const { coordinates, horizontalAccuracy } = position;
  console.log(coordinates, horizontalAccuracy);
}

The iOS prompt shows a default message, which the locationFullAccuracyPermission config plugin option can replace.

An approximate location is accurate to kilometers rather than meters. To get it, request the permission with accuracy: RequestPermissionsAccuracyOption.REDUCED.

On Android, this requests only ACCESS_COARSE_LOCATION, so the permission dialog does not offer the precise location.

On iOS, the app does not ask to upgrade to the precise location. To make the approximate location the default in the permission dialog, set isIosReducedAccuracyByDefault to true in the config plugin. If the app never asks for the precise location, also set locationFullAccuracyPermission to false to omit the purpose string of the temporary full accuracy prompt:

{
  "expo": {
    "plugins": [
      [
        "expo-location",
        {
          "isIosReducedAccuracyByDefault": true,
          "locationFullAccuracyPermission": false
        }
      ]
    ]
  }
}

Then request reduced accuracy:

import { Location, RequestPermissionsAccuracyOption } from 'expo-location/next';

async function requestApproximateLocation() {
  const { granted } = await Location.requestForegroundPermissions({
    accuracy: RequestPermissionsAccuracyOption.REDUCED,
  });
  if (!granted) {
    return;
  }
  const position = await Location.getPosition();
  if (!position) {
    return;
  }
  const { coordinates, horizontalAccuracy } = position;
  console.log(coordinates, horizontalAccuracy);
}

getPosition resolves with a single fix. It returns a cached fix when one is younger than maxCachedAge. Otherwise, it waits up to timeout seconds for a new one and falls back to the last known location when none arrives. Both values are in seconds. Check timestamp when freshness matters.

When timeout is set to 0, the call resolves immediately with the last known position, without asking for a new fix.

import { Location, LocationProfile } from 'expo-location/next';

async function getFreshPosition() {
  const position = await Location.getPosition({
    maxCachedAge: 30,
    timeout: 15,
    profile: LocationProfile.DEFAULT,
  });
  if (!position) {
    console.log('No location available');
    return null;
  }
  const ageSeconds = (Date.now() - position.timestamp) / 1000;
  if (ageSeconds > 30) {
    console.log(`Fell back to a fix from ${Math.round(ageSeconds)} seconds ago`);
  }
  return position;
}

When the user denies the permission, canAskAgain tells whether the system shows the dialog again. When it is false, the only way to grant the permission is the system settings, so send the user there.

import { Location } from 'expo-location/next';
import { Linking } from 'react-native';

async function ensureForegroundPermission() {
  const permission = await Location.requestForegroundPermissions();
  if (permission.granted) {
    return true;
  }
  if (!permission.canAskAgain) {
    await Linking.openSettings();
  }
  return false;
}

On Android, the background permission requires the foreground permission first. The request throws when the foreground permission is not granted. Receiving positions in the background also needs the background permission declared on Android and the background mode on iOS. Enable both in the config plugin:

{
  "expo": {
    "plugins": [
      [
        "expo-location",
        {
          "isIosBackgroundLocationEnabled": true,
          "isAndroidBackgroundLocationEnabled": true
        }
      ]
    ]
  }
}

On Android 11 and later, the system opens the app's settings page instead of a dialog. The request resolves when the user comes back.

isAndroidBackgroundLocationEnabled adds five permissions: ACCESS_BACKGROUND_LOCATION, RECEIVE_BOOT_COMPLETED, FOREGROUND_SERVICE, FOREGROUND_SERVICE_LOCATION, and POST_NOTIFICATIONS. The last three are for the location foreground service; set isAndroidForegroundServiceEnabled to false to leave them out.

On iOS, the request shows the Change to Always Allow dialog. Answering Keep Only While Using resolves with status: "denied" and scope: "whenInUse", because the foreground permission stays granted.

import { Location, LocationScope } from 'expo-location/next';

async function requestBackgroundPermission() {
  const { granted } = await Location.requestForegroundPermissions();
  if (!granted) {
    return false;
  }
  const { scope } = await Location.requestBackgroundPermissions();
  return scope === LocationScope.ALWAYS;
}

watchPosition returns a handle that controls the native watcher. Pause it when the screen loses focus, resume it when the screen is back, and dispose it when the screen unmounts. A screen that loses focus stays mounted behind another tab, a pushed screen, or a modal. On Android, the watcher also pauses on its own while the app is in the background, unless a location foreground service is running.

import { Location, LocationProfile, PositionWatchHandle } from 'expo-location/next';
import { useFocusEffect } from 'expo-router';
import { useCallback, useEffect, useRef } from 'react';

export default function LiveMapScreen() {
  const watcher = useRef<PositionWatchHandle | null>(null);

  useEffect(() => {
    watcher.current = Location.watchPosition({
      profile: LocationProfile.OTHER_NAVIGATION,
      onPosition: position => console.log(position.coordinates),
      onError: error => console.warn(error.message),
    });
    return () => {
      watcher.current?.dispose();
      watcher.current = null;
    };
  }, []);

  useFocusEffect(
    useCallback(() => {
      watcher.current?.resume();
      return () => watcher.current?.pause();
    }, [])
  );

  return null;
}

Location services are a device-wide switch, separate from the app's permission. With services off, no app receives a position. On Android, enableLocationServices asks the user to turn them on: Google Play services shows an in-app prompt, and the Android provider opens the system settings. Both require the app to be in the foreground with a current Activity. On iOS, only the user can turn them on in Settings.

import { Location } from 'expo-location/next';
import { Alert, Platform } from 'react-native';

async function ensureLocationServices() {
  if (Location.hasLocationServicesEnabled()) {
    return true;
  }
  if (Platform.OS === 'android') {
    return Location.enableLocationServices();
  }
  Alert.alert(
    'Location Services are off',
    'Turn them on in Settings > Privacy & Security > Location Services.'
  );
  return false;
}

To receive positions while the app is in the background, define a task with defineLocationTask at the top level of a module. Then start the delivery with LocationUpdatesHandle. This requires expo-task-manager, the background permission, ACCESS_BACKGROUND_LOCATION and RECEIVE_BOOT_COMPLETED declared on Android, and the location background mode on iOS. Enable the last two in the config plugin:

{
  "expo": {
    "plugins": [
      [
        "expo-location",
        {
          "isIosBackgroundLocationEnabled": true,
          "isAndroidBackgroundLocationEnabled": true
        }
      ]
    ]
  }
}

Positions keep arriving after the app process has ended; the system starts the app in the background to deliver them. While the app is in the background, Android delivers positions only a few times each hour.

import { defineLocationTask } from 'expo-location/next';

defineLocationTask({
  onPosition: position => {
    console.log('Background position', position.coordinates);
  },
  onError: error => {
    console.warn('Background updates failed', error.message);
  },
});

Import that module from the root layout, so the task exists on every launch, including the relaunch after the system terminated the app:

import '../locationTask';

Then control the delivery from a screen:

import {
  Location,
  LocationProfile,
  LocationScope,
  LocationUpdatesHandle,
} from 'expo-location/next';
import { useEffect, useState } from 'react';
import { Button, View } from 'react-native';

const locationUpdates = new LocationUpdatesHandle().withProfile(LocationProfile.LOW_POWER);

export default function TrackingScreen() {
  const [isTracking, setIsTracking] = useState(false);

  useEffect(() => {
    locationUpdates.hasStarted().then(setIsTracking);
  }, []);

  async function start() {
    const foreground = await Location.requestForegroundPermissions();
    if (!foreground.granted) {
      return;
    }
    const { scope } = await Location.requestBackgroundPermissions();
    if (scope !== LocationScope.ALWAYS) {
      return;
    }
    await locationUpdates.start();
    setIsTracking(true);
  }

  async function stop() {
    await locationUpdates.stop();
    setIsTracking(false);
  }

  return (
    <View>
      <Button
        title={isTracking ? 'Stop tracking' : 'Start tracking'}
        onPress={isTracking ? stop : start}
      />
    </View>
  );
}

On Android, a profile means something different for a background task than for a watcher. LOW_POWER waits much longer between positions, batches them, and skips positions close to the last one, so a device that stays put may produce none. AUTOMOTIVE_NAVIGATION delivers as often as the system allows, with no batching and no distance filter.

Both sides default to the same task name, so you can omit it. To run several tasks, give each task its own name and pass that name to both defineLocationTask and the LocationUpdatesHandle constructor.

On Android 8 and later, while the app is backgrounded, the watchers stop and location tasks trigger rarely. If you want a steady stream of position fixes in the background, start a background session with ensureBackgroundSessionStarted. The session runs as a location foreground service with a notification. You can start it only while the app is in the foreground. It needs the FOREGROUND_SERVICE and FOREGROUND_SERVICE_LOCATION permissions, so set isAndroidForegroundServiceEnabled to true in the config plugin.

The call to ensureBackgroundSessionStarted persists the configuration passed to it. With the configuration present, the module restarts the background session whenever the app enters the foreground, even after the app is closed and reopened.

import { Location } from 'expo-location/next';
import { Platform } from 'react-native';

async function startTracking() {
  if (Platform.OS !== 'android') {
    return;
  }
  const { granted } = await Location.requestForegroundPermissions();
  if (!granted) {
    return;
  }
  await Location.requestNotificationPermissions();
  await Location.ensureBackgroundSessionStarted({
    notificationTitle: 'Tracking your route',
    notificationBody: 'Tap to return to the app',
  });
}

async function stopTracking() {
  if (Platform.OS !== 'android') {
    return;
  }
  await Location.stopBackgroundSession();
}

If you no longer need the background session, you need to manually stop it using stopBackgroundSession.