Expo Location (next)

By default, a permission request asks for the precise location. On Android, this requests ACCESS_FINE_LOCATION. 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.

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. 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.

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.

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. 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 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
        }
      ]
    ]
  }
}

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>
  );
}

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.