Skip to content

Recipe: foreground → background location ​

Problem. Your app needs background location (running tracker, ride-share driver mode, etc.), but both iOS and Android require you to request the foreground permission first and only then ask for the always/background permission. The native APIs expose both as separate permissions, and getting the order wrong throws a confusing OS error.

Solution. Use Permissions.BUNDLES.LOCATION_BACKGROUND. On Android it expands to [ACCESS_FINE_LOCATION, ACCESS_BACKGROUND_LOCATION] — two independent runtime permissions that must be requested in order. On iOS it expands to just [LOCATION_WHEN_IN_USE] because iOS models Core Location as a single authorization: you request "When In Use" first, then upgrade to "Always" as a follow-up step on the same permission rather than as a separate request. Feed the bundle into a sequential useMultiplePermissions call and the flow Just Works on both platforms — on iOS you'll see one prompt, on Android two.

What you'll use ​

Code ​

tsx
import React from "react";
import { Button, Text, View } from "react-native";
import { useMultiplePermissions } from "react-native-permission-handler";
import { Permissions } from "react-native-permission-handler/rnp";

// iOS: ["LOCATION_WHEN_IN_USE"] — one entry.
// Android: ["ACCESS_FINE_LOCATION", "ACCESS_BACKGROUND_LOCATION"] — two entries.
const LOCATION_BUNDLE = Permissions.BUNDLES.LOCATION_BACKGROUND;

const entries = LOCATION_BUNDLE.map((permission, index) => {
  const isBackground = index === 1; // only exists on Android
  return isBackground
    ? {
        id: "location-background",
        permission,
        prePrompt: {
          title: "Always allow location",
          message:
            "We need background location so your run keeps recording when the screen is off.",
        },
        blockedPrompt: {
          title: "Background location blocked",
          message: "Switch location to 'Always' in Settings for background tracking.",
        },
      }
    : {
        id: "location-foreground",
        permission,
        prePrompt: {
          title: "Location while using the app",
          message: "We need your location to track your run in real time.",
        },
        blockedPrompt: {
          title: "Location blocked",
          message: "Enable location access in Settings to continue.",
        },
      };
});

export function LiveTrackingSetup() {
  const perms = useMultiplePermissions({
    strategy: "sequential",
    permissions: entries,
    onAllGranted: () => startTracking(),
  });

  if (perms.allGranted) return <Text>Tracking…</Text>;

  return (
    <View>
      <Text>Enable location to start tracking your run.</Text>
      <Button title="Enable location" onPress={perms.request} />
      {perms.blockedPermissions.length > 0 && (
        <Text>Resolve the blocked permissions above, then tap again.</Text>
      )}
    </View>
  );
}

function startTracking() {
  // ...
}

Why sequential, not parallel ​

On both iOS and Android, requesting background location before foreground is granted either no-ops or outright fails. Sequential enforces the correct order: the background entry won't be prompted until the foreground entry returns granted. If the user denies or dismisses the foreground prompt, the flow stops — tap the "Enable location" button again to resume from the beginning, or call perms.resume() to continue from the current ungranted step.

iOS "Always" upgrades ​

Permissions.BUNDLES.LOCATION_BACKGROUND on iOS intentionally contains only [LOCATION_WHEN_IN_USE] — iOS models Core Location as a single authorization, so the bundle only drives the foreground half. Request "Always" as a follow-up step with a second handler for Permissions.LOCATION_ALWAYS, gated on LOCATION_WHEN_IN_USE already being granted:

tsx
function AlwaysAllowUpgradeButton() {
  const whenInUse = usePermissionHandler({
    permission: Permissions.LOCATION_WHEN_IN_USE,
    prePrompt: { title: "Location", message: "Find nearby stops." },
  });

  const always = usePermissionHandler({
    permission: Permissions.LOCATION_ALWAYS,
    prePrompt: {
      title: "Background location",
      message: "Keep tracking your run while the screen is off.",
    },
    autoCheck: false,
    renderPrePrompt: ({ onConfirm, onCancel }) => (
      <AlwaysUpgradeModal onAllow={onConfirm} onSkip={onCancel} />
    ),
  });

  if (!whenInUse.isGranted) return null;

  return (
    <View>
      <Text>Tracking works while the app is open. For background tracking, allow "Always."</Text>
      <Button title="Allow Always" onPress={always.check} />
      {always.ui}
    </View>
  );
}

always.check re-checks LOCATION_ALWAYS through the engine; when the check reports denied (still requestable), always.ui renders renderPrePrompt's output, and onConfirm fires always.request(), which triggers the native "Always" system dialog.

Gotcha: on iOS, request LOCATION_ALWAYS only after LOCATION_WHEN_IN_USE is granted — requesting it first fails. This flow requires react-native-permissions >= 5.5.3, where check(LOCATION_ALWAYS) correctly reports denied (requestable) rather than blocked once "When In Use" is granted.

If the user denies or blocks the "Always" system dialog, fall back to always.openSettings() — as of v0.8.0, engine.openSettings("location") deep-links into the iOS Location Services sub-page, so flipping "When Using the App" to "Always" is one tap away.

On Android, openSettings already lands on the app-specific permissions page (the permission parameter is ignored), and Permissions.BUNDLES.LOCATION_BACKGROUND handles the second prompt via the ACCESS_BACKGROUND_LOCATION entry. The iOS branch above is the asymmetry that the bundle cannot hide.

Handling partial grants (Android) ​

On Android, the user can grant foreground location and then deny background. Because each entry has its own blockedPrompt, the flow will surface the blocked modal for the background entry while keeping foreground granted. Use perms.blockedPermissions to show a summary row.

See also: