Skip to main content
The UserLocation component displays the user’s current location on the map with customizable appearance and behavior.

​
Basic Usage

import { MapView, Camera, UserLocation } from '@rnmapbox/maps';

<MapView>
  <Camera followUserLocation />
  <UserLocation visible={true} />
</MapView>

​
Props

​
androidRenderMode
'normal' | 'compass' | 'gps'
Android-only render mode for the location indicator.
  • normal: Simple circle
  • compass: Triangle with heading
  • gps: Large arrow
Platform: Android only
​
animated
boolean
default:"true"
Whether the location icon is animated between updates.
​
children
ReactElement | ReactElement[]
Custom location icon using Mapbox GL Native components. When provided, replaces the default location indicator.
<UserLocation>
  <CircleLayer
    id="custom-location"
    style={{ circleRadius: 10, circleColor: '#007AFF' }}
  />
</UserLocation>
​
minDisplacement
number
default:"0"
Minimum distance (in meters) the device must move before the GPS location is updated.
<UserLocation minDisplacement={10} />
​
onPress
() => void
Callback function triggered when the location icon is pressed.
<UserLocation 
  onPress={() => console.log('Location pressed')}
/>
​
onUpdate
(location: Location) => void
Callback function triggered when the location is updated.
<UserLocation 
  onUpdate={(location) => {
    console.log('Location:', location.coords);
  }}
/>
​
renderMode
UserLocationRenderMode
default:"UserLocationRenderMode.Normal"
Deprecated: Use LocationPuck component instead of UserLocationRenderMode.Native.Specifies which render mode to use:
  • UserLocationRenderMode.Normal: Custom React Native rendering
  • UserLocationRenderMode.Native: Native platform rendering
​
requestsAlwaysUse
boolean
default:"false"
Request “always” location permission to track location even when the app is in the background.Platform: iOS only
​
showsUserHeadingIndicator
boolean
default:"false"
Show or hide a small arrow indicating the direction the device is pointing relative to north.
​
visible
boolean
default:"true"
Controls whether the location icon is visible on the map.

​
Types

​
Location

​
coords
Coordinates
required
Location coordinates object.
​
timestamp
number
Unix timestamp (in milliseconds) when the location was determined.

​
Coordinates

​
latitude
number
required
The latitude in degrees.
​
longitude
number
required
The longitude in degrees.
​
heading
number
The heading (measured in degrees) relative to true north. Indicates the direction the device is pointing to (compass value).Note: On Android, this may incorrectly report the course value. See issue #1213.
​
course
number
The direction in which the device is traveling, measured in degrees relative to due north. Different from heading - this is the actual direction of movement.
​
speed
number
The instantaneous speed of the device, measured in meters per second.
​
accuracy
number
The radius of uncertainty for the location, measured in meters.
​
altitude
number
The altitude, measured in meters.

​
Methods

​
setLocationManager

setLocationManager({ running }: { running?: boolean }): Promise<void>
Control whether to start or stop listening to location updates. Note: Location listening starts automatically when either onUpdate or visible props are set.
​
running
boolean
true to start listening, false to stop.

​
needsLocationManagerRunning

needsLocationManagerRunning(): boolean
Returns whether the location manager should be running based on current props.

​
Examples

​
Basic User Location

import { MapView, Camera, UserLocation } from '@rnmapbox/maps';

function MyMap() {
  return (
    <MapView>
      <Camera followUserLocation />
      <UserLocation visible={true} />
    </MapView>
  );
}

​
With Location Updates

import { MapView, UserLocation } from '@rnmapbox/maps';
import { useState } from 'react';

function MyMap() {
  const [location, setLocation] = useState(null);
  
  return (
    <MapView>
      <UserLocation 
        onUpdate={(location) => setLocation(location.coords)}
      />
    </MapView>
  );
}

​
Custom Location Indicator

import { MapView, UserLocation, CircleLayer } from '@rnmapbox/maps';

function MyMap() {
  return (
    <MapView>
      <UserLocation animated={true}>
        <CircleLayer
          id="user-location-pulse"
          style={{
            circleRadius: 20,
            circleColor: '#007AFF',
            circleOpacity: 0.3,
          }}
        />
        <CircleLayer
          id="user-location-dot"
          style={{
            circleRadius: 8,
            circleColor: '#007AFF',
          }}
        />
      </UserLocation>
    </MapView>
  );
}

​
With Minimum Displacement

<UserLocation
  minDisplacement={10}
  onUpdate={(location) => {
    console.log('User moved at least 10 meters');
  }}
/>

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us