react-native-background-location

Background GPS tracking and geofencing for React Native, built on the New Architecture.

A TurboModule for the React Native New Architecture. Drives a foreground service on Android and CLLocationManager on iOS, persists every fix to Room and Core Data, and ships native geofencing plus crash recovery so trips survive process death.

Read the full documentation

Features

• Background tracking with configurable accuracy and distance filter
• Native geofencing (GeofencingClient on Android, CLCircularRegion on iOS)
• Persistent location storage (Room on Android, Core Data on iOS)
• Crash recovery via WorkManager and significant location monitoring
• React hooks: useBackgroundLocation, useLocationPermissions, useLocationUpdates, useLocationTracking
• Expo config plugin for managed workflows

Requirements

| Requirement | Version | | -------------- | ---------------------------------- | | React Native | >=0.73 (New Architecture required) | | iOS | >=16.0 | | Android minSdk | 24 |

Installation

Bare React Native (recommended)

yarn add @gabriel-sisjr/react-native-background-location
cd ios && pod install

Autolinking handles Android manifest merging and iOS pod registration. Bare iOS apps must still add NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, NSLocationAlwaysUsageDescription, and a UIBackgroundModes entry containing location to their Info.plist. See the iOS setup guide for full details.

Quick Start

import {
  startTracking,
  useLocationUpdates,
} from '@gabriel-sisjr/react-native-background-location';

function App() {
  const { locations } = useLocationUpdates();

  return (
    <Button
      title="Start"
      onPress={() => startTracking({ tripId: 'trip-1', distanceFilter: 10 })}
    />
  );
}

See the documentation site for the full hook reference and the permission flow that must run before tracking starts.

Documentation

• Getting Started
• API Reference
• Hooks
• Geofencing Guide
• Expo Config Plugin
• Troubleshooting

License

MIT — see LICENSE.