react-native-geolocation-plus

This is a fork of @react-native-community/geolocation v3.4.0, created to fix two real bugs found while investigating production GPS-hang incidents in an Android app, and to add a capability the original library doesn't expose. Full credit to michalchudziak and the React Native Community for the original library — see Fork rationale below for exactly what's different and why. This fork is Android-only; iOS/web behavior is unchanged from upstream but untested here.

The Geolocation API 📍 module for React Native that extends the Geolocation web spec.

Supports TurboModules ⚡️ and legacy React Native architecture.

Fully compatible with TypeScript.

Supports modern Play Services Location API.

Fork rationale

Four fixes, all in the Android native code, none of which change existing behavior for callers who don't opt in:

1. Play Services getCurrentPosition() silently ignored the timeout option. PlayServicesLocationManager read maximumAge but never timeout — a single-shot location request under Play Services could hang indefinitely with no cutoff at all, unlike the raw-provider path which already enforced one. Now it does, with the same 10-minute default as the raw provider when timeout isn't specified.
2. Only two of Play Services' four accuracy tiers were reachable. enableHighAccuracy mapped to either PRIORITY_HIGH_ACCURACY (GPS-grade) or PRIORITY_LOW_POWER (~10km, city-level — too coarse for most proximity/geofence checks). A new accuracy option ('high' | 'balanced' | 'low' | 'passive') reaches all four Play Services tiers, including PRIORITY_BALANCED_POWER_ACCURACY (~100m, block-level) — see getCurrentPosition() below. The default when accuracy isn't set also changed: enableHighAccuracy: false now maps to balanced instead of low, since city-level accuracy is rarely what anyone actually wants. (The raw LocationManager fallback has only two real providers, so there accuracy collapses to the same GPS-vs-network choice enableHighAccuracy already made.)
3. The raw LocationManager provider selection hard-failed on a permission mismatch instead of falling back. If a user granted only "Approximate" location (ACCESS_COARSE_LOCATION, no ACCESS_FINE_LOCATION) and the app requested enableHighAccuracy: true, getValidProvider() returned null — "No location provider available" — instead of retrying with NETWORK_PROVIDER, which the app may have had perfectly usable permission for. It now retries in that case, same as it already did for a disabled (not just unauthorized) provider.
4. Concurrent getCurrentPosition() calls under Play Services could permanently hang one of them. The single-shot path used to track the in-flight callback and timeout in shared instance fields on PlayServicesLocationManager (one instance for the app's whole lifetime). If two calls overlapped, whichever resolved first would silently cancel the other's timeout and unregister its listener via those shared fields, leaving it unresolved forever regardless of its own timeout value. Fixed by switching to FusedLocationProviderClient.getCurrentLocation(CurrentLocationRequest, CancellationToken) — Google's own documented, currently-recommended API for single-shot fetches, which gives each call an independent Task with no shared state, eliminating the bug structurally rather than patching around it. This also let us delete the manual Handler/Runnable/CallbackHolder bookkeeping the old approach needed (net -111 lines).

Full commit-by-commit history: compare against upstream master.

Supported platforms

| Platform | Support | |---|---| | iOS | ✅ | | Android | ✅ | | Web | ✅ | | Windows | ❌ | | macOS | ❌ |

Compatibility

| React Native | RNC Geoloaction | |---|---| | >= 0.73.0 | >= 3.2.0 | | >= 0.70.0 | >= 3.0.0 < 3.2.0 | | >= 0.64.0 | 2.x.x | | <= 0.63.0 | 1.x.x |

Getting started

yarn add react-native-geolocation-plus

or

npm install react-native-geolocation-plus --save

Import path is unchanged from upstream:

import Geolocation from 'react-native-geolocation-plus';

Configuration and Permissions

iOS

You need to include NSLocationWhenInUseUsageDescription and NSLocationAlwaysAndWhenInUseUsageDescription in Info.plist to enable geolocation when using the app. If your app supports iOS 10 and earlier, the NSLocationAlwaysUsageDescription key is also required. If these keys are not present in the Info.plist, authorization requests fail immediately and silently. Geolocation is enabled by default when you create a project with react-native init.

In order to enable geolocation in the background, you need to include the 'NSLocationAlwaysUsageDescription' key in Info.plist and add location as a background mode in the 'Capabilities' tab in Xcode.

IOS >= 15 Positions will also contain a mocked boolean to indicate if position was created from a mock provider / software.

Android

To request access to location, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

or

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Android API >= 18 Positions will also contain a mocked boolean to indicate if position was created from a mock provider.

• android/settings.gradle

include ':react-native-community-geolocation'
project(':react-native-community-geolocation').projectDir = new File(rootProject.projectDir, '../node_modules/@react-native-community/geolocation/android')

• android/app/build.gradle

dependencies {
   ...
   implementation project(':react-native-community-geolocation')
}

• android/app/src/main/.../MainApplication.java On imports section:

import com.reactnativecommunity.geolocation.GeolocationPackage;

In the class at getPackages method:

@Override
protected List<ReactPackage> getPackages() {
      @SuppressWarnings("UnnecessaryLocalVariable")
      List<ReactPackage> packages = new PackageList(this).getPackages();
      // Packages that cannot be autolinked yet can be added manually here, for example:
      packages.add(new GeolocationPackage()); // <== add this line
      return packages;
}

Migrating from the core react-native module

This module was created when the Geolocation was split out from the core of React Native. As a browser polyfill, this API was available through the navigator.geolocation global - you didn't need to import it. To migrate to this module you need to follow the installation instructions above and change following code:

navigator.geolocation.setRNConfiguration(config);

to:

import Geolocation from '@react-native-community/geolocation';

Geolocation.setRNConfiguration(config);

If you need to have geolocation API aligned with the browser (cross-platform apps), or want to support backward compatibility, please consider adding following lines at the root level, for example at the top of your App.js file (only for react native):

navigator.geolocation = require('@react-native-community/geolocation');

Usage

Example

import Geolocation from '@react-native-community/geolocation';

Geolocation.getCurrentPosition(info => console.log(info));

Check out the example project for more examples.

Methods

Summary

• setRNConfiguration
• requestAuthorization
• getCurrentPosition
• watchPosition
• clearWatch
• stopObserving

Details

setRNConfiguration()

Sets configuration options that will be used in all location requests.

Geolocation.setRNConfiguration(
  config: {
    skipPermissionRequests: boolean;
    authorizationLevel?: 'always' | 'whenInUse' | 'auto';
    enableBackgroundLocationUpdates?: boolean;
    locationProvider?: 'playServices' | 'android' | 'auto';
  }
) => void

Supported options:

• skipPermissionRequests (boolean) - Defaults to false. If true, you must request permissions before using Geolocation APIs.
• authorizationLevel (string, iOS-only) - Either "whenInUse", "always", or "auto". Changes whether the user will be asked to give "always" or "when in use" location services permission. Any other value or auto will use the default behaviour, where the permission level is based on the contents of your Info.plist.
• enableBackgroundLocationUpdates (boolean, iOS-only) - When using skipPermissionRequests, toggle wether to automatically enableBackgroundLocationUpdates. Defaults to true.
• locationProvider (string, Android-only) - Either "playServices", "android", or "auto". Determines wether to use Google’s Location Services API or Android’s Location API. The "auto" mode defaults to android, and falls back to Android's Location API if play services aren't available.

requestAuthorization()

Request suitable Location permission.

  Geolocation.requestAuthorization(
    success?: () => void,
    error?: (
      error: {
        code: number;
        message: string;
        PERMISSION_DENIED: number;
        POSITION_UNAVAILABLE: number;
        TIMEOUT: number;
      }
    ) => void
  )

On iOS if NSLocationAlwaysUsageDescription is set, it will request Always authorization, although if NSLocationWhenInUseUsageDescription is set, it will request InUse authorization.

getCurrentPosition()

Invokes the success callback once with the latest location info.

  Geolocation.getCurrentPosition(
    success: (
      position: {
        coords: {
          latitude: number;
          longitude: number;
          altitude: number | null;
          accuracy: number;
          altitudeAccuracy: number | null;
          heading: number | null;
          speed: number | null;
        };
        timestamp: number;
      }
    ) => void,
    error?: (
      error: {
        code: number;
        message: string;
        PERMISSION_DENIED: number;
        POSITION_UNAVAILABLE: number;
        TIMEOUT: number;
      }
    ) => void,
    options?: {
        timeout?: number;
        maximumAge?: number;
        enableHighAccuracy?: boolean;
        accuracy?: 'high' | 'balanced' | 'low' | 'passive';
    }
  )

Supported options:

• timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to 10 minutes. Now actually enforced on Android when using the Play Services provider — upstream v3.4.0 silently ignored this option under Play Services.

• maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.

• enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested. Superseded by accuracy when both are set.

• accuracy (Android only, new in this fork) - 'high' | 'balanced' | 'low' | 'passive'. Under Play Services (locationProvider: 'playServices'), selects one of its four LocationRequest.Priority tiers directly:

  • 'high' → PRIORITY_HIGH_ACCURACY (GPS-grade)
  • 'balanced' → PRIORITY_BALANCED_POWER_ACCURACY (~100m, block-level — a good default for proximity/geofence checks; not reachable via enableHighAccuracy alone)
  • 'low' → PRIORITY_LOW_POWER (~10km, city-level)
  • 'passive' → PRIORITY_PASSIVE (no active fetch — only receive locations other apps/system requested)

  If omitted, falls back to enableHighAccuracy ? 'high' : 'balanced' — note this is 'balanced', not 'low' as upstream's equivalent fallback effectively was.

  Under the raw LocationManager fallback (locationProvider: 'android', or when Play Services isn't available), there's no four-tier equivalent — only GPS_PROVIDER and NETWORK_PROVIDER exist, so accuracy collapses to a binary choice: 'high' requests GPS_PROVIDER, anything else requests NETWORK_PROVIDER (the same provider enableHighAccuracy: false already requested).

watchPosition()

Invokes the success callback whenever the location changes. Returns a watchId (number).

  Geolocation.watchPosition(
    success: (
      position: {
        coords: {
          latitude: number;
          longitude: number;
          altitude: number | null;
          accuracy: number;
          altitudeAccuracy: number | null;
          heading: number | null;
          speed: number | null;
        };
        timestamp: number;
      }
    ) => void,
    error?: (
      error: {
        code: number;
        message: string;
        PERMISSION_DENIED: number;
        POSITION_UNAVAILABLE: number;
        TIMEOUT: number;
      }
    ) => void,
    options?: {
      interval?: number;
      fastestInterval?: number;
      timeout?: number;
      maximumAge?: number;
      enableHighAccuracy?: boolean;
      accuracy?: 'high' | 'balanced' | 'low' | 'passive';
      distanceFilter?: number;
      useSignificantChanges?: boolean;
    }
  ) => number

Supported options:

• interval (ms) -- (Android only) The rate in milliseconds at which your app prefers to receive location updates. Note that the location updates may be somewhat faster or slower than this rate to optimize for battery usage, or there may be no updates at all (if the device has no connectivity, for example).
• fastestInterval (ms) -- (Android only) The fastest rate in milliseconds at which your app can handle location updates. Unless your app benefits from receiving updates more quickly than the rate specified in interval, you don't need to set it.
• timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to 10 minutes. Not applicable here in practice — watchPosition is continuous, this fork's timeout fix only applies to single-shot getCurrentPosition calls.
• maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
• enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested. Superseded by accuracy when both are set.
• accuracy (Android only, new in this fork) - 'high' | 'balanced' | 'low' | 'passive'. See getCurrentPosition() above for what each tier maps to.
• distanceFilter (m) - The minimum distance from the previous location to exceed before returning a new location. Set to 0 to not filter locations. Defaults to 100m.
• useSignificantChanges (bool) - Uses the battery-efficient native significant changes APIs to return locations. Locations will only be returned when the device detects a significant distance has been breached. Defaults to FALSE.

clearWatch()

Clears watch observer by id returned by watchPosition()

Geolocation.clearWatch(watchID: number);

This fork

Maintained by prateek00739 — see Fork rationale at the top of this README for what's different from upstream and why. Issues/PRs against the fork-specific changes (the three fixes listed above) are welcome here; issues against the rest of the library's behavior are likely better raised upstream.

Upstream maintainers

The section below is from the original project and describes it, not this fork.

This module is developed and maintained by michalchudziak.

I owe a lot to the fantastic React & React Native community, and I contribute back with my free time 👨🏼‍💼💻 so if you like the project, please star it ⭐️!

If you need any help with this module, or anything else, feel free to reach out to me! I provide boutique consultancy services for React & React Native. Just visit my website, or send me an email at [email protected] 🙏🏻

Co-maintainers needed

Due to personal commitments, recently I am unable to dedicate the necessary time to maintain this library as it deserves. I’m looking for passionate contributors to help keep the project alive and thriving. If you're interested in contributing or taking on a maintainer role, please reach out [email protected] — your support would mean a lot!

Contributors

This module was extracted from react-native core. Please refer to https://github.com/react-native-community/react-native-geolocation/graphs/contributors for the complete list of contributors.

License

The library is released under the MIT licence. For more information see LICENSE.