React Native Geolocation: The Web API on Mobile

WHY IT EXISTS React Native core doesn't bundle every possible native API. A dedicated library is needed to bridge the native location services, like iOS's Core Location and Android's Play Services Location API, to JavaScript in a consistent, cross-platform way. This library fills that gap for projects that aren't using a managed framework like Expo.

THE MENTAL MODEL Treat this library as the mobile equivalent of the web's standard navigator.geolocation API. It provides the same core functions like getCurrentPosition and watchPosition. If you know how to get a user's location on a website, you already understand the core API design here. It's a bridge, not a new invention.

HOW IT WORKS The library exposes a JavaScript API that calls down to native modules on each platform. On Android, it uses the modern Google Play Services Location API for better accuracy and battery efficiency. On iOS, it wraps the standard Core Location framework. This abstraction handles the platform-specific implementation details, so you can write one set of location-aware code in your app. It also supports React Native's modern TurboModule architecture for improved performance.

WHEN TO USE IT Use this library in any bare React Native project (or an ejected Expo project) when you need to get the device's geographic coordinates. It's ideal for one-time position checks, such as finding nearby stores, or for continuous tracking, like in a running app or for live delivery updates.

WHEN NOT TO USE IT If you are using the managed Expo workflow, Expo provides its own expo-location module, which is more tightly integrated and requires less native configuration. Use this community library primarily for bare React Native projects. Also, note that it only provides raw coordinate data; it does not include any UI components like maps.

ONE CANONICAL EXAMPLE The most common and frustrating footgun is improper iOS configuration. To request location permissions, you must add keys and descriptions to your Info.plist file. For example, to request permission only while the app is in use, you must add the NSLocationWhenInUseUsageDescription key with a string explaining why you need the user's location. If this key and its corresponding string are missing, any call to request permissions will fail immediately and silently, with no error or console log to indicate what went wrong.