react-native-mapbox-gl/API.md

iOS API Docs

Access token

The first thing you need to do before using the map is getting a Mapbox access token by signing up to a Mapbox account.

Then, make sure you run this before mounting any MapViews:

import Mapbox from 'react-native-mapbox-gl';
Mapbox.setAccessToken('your-mapbox.com-access-token');

Props

Import the component to use it:

import { MapView } from 'react-native-mapbox-gl';
<MapView />

Prop	Type	Required	Description	Default
initialCenterCoordinate	object	Optional	Initial latitude/longitude the map will load at.	{ latitude:0, longitude: 0 }
initialZoomLevel	number	Optional	Initial zoom level the map will load at. 0 is the entire world, 18 is rooftop level.	0
initialDirection	number	Optional	Initial heading of the map in degrees, where 0 is north and 180 is south	0
rotateEnabled	boolean	Optional	Whether the map can rotate.	true
scrollEnabled	boolean	Optional	Whether the map can be scrolled.	true
zoomEnabled	boolean	Optional	Whether the map zoom level can be changed.	true
showsUserLocation	boolean	Optional	Whether the user's location is shown on the map. Note: The map will not zoom to their location.	false
userTrackingMode	enum	Optional	Wether the map is zoomed to and follows the user's location. One of Mapbox.userTrackingMode.none, Mapbox.userTrackingMode.follow, Mapbox.userTrackingMode.followWithCourse, Mapbox.userTrackingMode.followWithHeading	Mapbox.userTrackingMode.none
userLocationVerticalAlignment	enum	Optional	Change the alignment of where the user location shows on the screen. One of Mapbox.userLocationVerticalAlignment.top, Mapbox.userLocationVerticalAlignment.center, Mapbox.userLocationVerticalAlignment.bottom	Mapbox.userLocationVerticalAlignment.center
styleURL	string	Required	A Mapbox style. See Styles for valid values.	Mapbox.mapStyles.streets
annotations	array	Optional	An array of annotation objects. See Annotations	[]
annotationsAreImmutable	boolean	Optional	Set this to true if you don't ever mutate the annotations array or the annotations themselves. This enables optimizations when props change.	false
attributionButtonIsHidden	boolean	Optional	Whether attribution button is visible in lower right corner. If true you must still attribute OpenStreetMap in your app.	false
logoIsHidden	boolean	Optional	Whether logo is visible in lower left corner.	false
compassIsHidden	boolean	Optional	Whether compass is visible when map is rotated.	false
contentInset	array	Optional	Change the padding of the viewport of the map. Offset is in pixels. [top, right, bottom, left] [0, 0, 0, 0]
style	React styles	Optional	Styles the actual map view container	N/A
debugActive	boolean	Optional	Turns on debug mode.	false

Callback props

<MapView onSomethingHappened={payload => {
  //...
}}/>

Prop	Payload shape	Description
onRegionWillChange	{latitude: 0, longitude: 0, zoomLevel: 0, direction: 0, pitch: 0, animated: false}	Fired when the map begins panning or zooming. animated indicates whether the action is user-driven or animation-driven.
onRegionDidChange	{latitude: 0, longitude: 0, zoomLevel: 0, direction: 0, pitch: 0, animated: false}	Fired when the map ends panning or zooming.
onOpenAnnotation	{id: 'marker_id', title: null, subtitle: null, latitude: 0, longitude: 0}	Fired when tapping an annotation.
onRightAnnotationTapped	{id: 'marker_id', title: null, subtitle: null, latitude: 0, longitude: 0}	Fired when user taps the rightCalloutAccessory of an annotation.
onChangeUserTrackingMode	Mapbox.userTrackingMode.none	Fired when the user tracking mode gets changed by an user pan or rotate.
onUpdateUserLocation	{latitude: 0, longitude: 0, headingAccuracy: 0, magneticHeading: 0, trueHeading: 0, isUpdating: false}	Fired when the user's location updates.
onLocateUserFailed	{message: 'Error message'}	Fired when there is an error getting the user's location. Do not rely on the string that is returned for determining what kind of error it is.
onTap	{latitude: 0, longitude: 0, screenCoordX: 0, screenCoordY: 0}	Fired when the users taps the screen.
onLongPress	{latitude: 0, longitude: 0, screenCoordX: 0, screenCoordX: 0}	Fired when the user taps and holds screen for 1 second.
onStartLoadingMap	undefined	Fired once the map begins loading the style.
onFinishLoadingMap	undefined	Fired once the map has loaded the style.

Methods

You first need to get a ref to your MapView component:

<MapView ref={map => { this._map = map; }} />

Then call methods as this._map.methodName().

---

this._map.setDirection(direction, animated = true, callback);
this._map.setZoomLevel(zoomLevel, animated = true, callback);
this._map.setCenterCoordinate(latitude, longitude, animated = true, callback);
this._map.setCenterCoordinateZoomLevel(latitude, longitude, zoomLevel, animated = true, callback);
this._map.setCenterCoordinateZoomLevelPitch(latitude, longitude, zoomLevel, pitch, animated = true, callback); // Android only
this._map.setPitch(pitch, animated = true, callback); // Android only
this._map.easeTo({ latitude, longitude, zoomLevel, direction, pitch }, animated = true, callback);

This set of methods sets the location the map is centered on, the zoom level, the heading and the pitch (Android only) of the map.

The transition to the desired location is animated by default, but can be made instantaneous by passing animated as false.

For easeTo, all arguments inside the options object are optional. You can specify any combination of center coords, zoomLevel, direction and pitch. What is not specified stays at their current values.

The methods accept an optional callback that will get fired when the animation has ended. Additionally, the return value is a promise that gets resolved when the animation has ended.

---

this._map.setVisibleCoordinateBounds(latitudeSW, longitudeSW, latitudeNE, longitudeNE, paddingTop = 0, paddingRight = 0, paddingBottom = 0, paddingLeft = 0, animated = true);

This method adjusts the center location and the zoomLevel of the map so that the rectangle determined by latitudeSW, longitudeSW, latitudeNE, longitudeNE fits inside the viewport.

You can optionally pass a minimum padding (in screen points) that will be visible around the given coordinate bounds.

The transition is animated unless you pass animated as false.

---

this._map.setCamera(latitude, longitude, fromDistance, pitch, direction, animationDuration = 0.3); // iOS Only

This method only works on iOS.

Sets the map pitched at an angle (pitch, measured in degrees, 0 is from straight above), looking towards latitude and longitude from fromDistance meters away, pointing towards heading direction.

Use animationDuration to adjust the speed of the transition.

---

this._map.getCenterCoordinateZoomLevel(data => {
  // ...
});

Gets the current coordinates and zoom level of the map.

data is an object of the form { latitude, longitude, zoomLevel }

---

this._map.getDirection(direction => {
  // ...
});

Gets the current heading of the map.

direction is the heading in degrees.

---

this._map.getPitch(pitch => { // Android only
  // ...
});

Gets the current tilt of the map. (Android only)

pitch is the tilt in degrees measured from the normal to the map.

---

this._map.getBounds(bounds => {
  // ...
});

Gets the bounding rectangle in GPS coordinates that is currently visible on within the map's viewport.

bounds is an array representing [ latitudeSW, longitudeSW, latitudeNE, longitudeNE ]

---

this._map.selectAnnotation(id, animated = true);

Selects the annotation tagged with id, as if it would be tapped by the user.

The transition is animated unless you pass animated as false.

Styles

Default styles

Mapbox GL ships with 6 included styles:

• Mapbox.mapStyles.streets
• Mapbox.mapStyles.emerald
• Mapbox.mapStyles.dark
• Mapbox.mapStyles.light
• Mapbox.mapStyles.satellite
• Mapbox.mapStyles.hybrid

To use one of these, just pass it as a prop to MapView:

<MapView
  styleURL={Mapbox.mapStyles.emerald}
/>

Custom styles

You can also create a custom style in Mapbox Studio and add it your map. Simply grab the style url. It should look something like:

mapbox://styles/bobbysud/cigtw1pzy0000aam2346f7ex0

Annotations

Object shape

[{
  coordinates, // required. For type polyline and polygon must be an array of arrays. For type point, single array with 2 coordinates
  type, // required. One of 'point', 'polyline' or 'polygon'
  title, // optional. Title string. Appears when marker pressed
  subtitle, // optional. Subtitle string. Appears when marker pressed
  fillAlpha, // optional. number. Only for type=polygon. Controls the opacity of the polygon
  fillColor, // optional. string. Only for type=polygon. CSS color (#rrggbb). Controls the fill color of the polygon
  strokeAlpha, // optional. number. Only for type=polygon or type=polyline. Controls the opacity of the line
  strokeColor, // optional. string. Only for type=polygon or type=polyline. CSS color (#rrggbb). Controls line color.
  strokeWidth, // optional. number. Only for type=polygon or type=polyline. Controls line width.
  id, // required. string. Unique identifier used for adding or selecting an annotation.
  annotationImage, { // optional. Marker image for type=point
    url, // required. string. Either remote image URL or 'image!yourImage'
    height, // required. number. Image height
    width, // required. number. Image width
  },
  rightCalloutAccessory, { // optional. iOS only. Clickable image that appears when type=point marker pressed
    url, // required. string. Either remote image URL or 'image!yourImage'
    height, // required. number. Image height
    width, // required. number. Image width
  },
}]

For adding local images via image!yourImage, on iOS see adding static resources to your app using Images.xcassets docs and on Android, put images in android/app/src/main/res/drawable/yourImage.png.

Example

annotations: [{
  coordinates: [40.72052634, -73.97686958312988],
  type: 'point',
  title: 'This is marker 1',
  subtitle: 'It has a rightCalloutAccessory too',
  rightCalloutAccessory: {
    url: 'https://cldup.com/9Lp0EaBw5s.png',
    height: 25,
    width: 25
  },
  annotationImage: {
    url: 'https://cldup.com/CnRLZem9k9.png',
    height: 25,
    width: 25
  },
  id: 'marker1'
}, {
  coordinates: [40.714541341726175,-74.00579452514648],
  type: 'point',
  title: 'Important',
  subtitle: 'Neat, this is a custom annotation image',
  annotationImage: {
    url: 'https://cldup.com/7NLZklp8zS.png',
    height: 25,
    width: 25
  },
  id: 'marker2'
}, {
  coordinates: [[40.76572150042782,-73.99429321289062],[40.743485405490695, -74.00218963623047],[40.728266950429735,-74.00218963623047],[40.728266950429735,-73.99154663085938],[40.73633186448861,-73.98983001708984],[40.74465591168391,-73.98914337158203],[40.749337730454826,-73.9870834350586]],
  type: 'polyline',
  strokeColor: '#00FB00',
  strokeWidth: 3,
  strokeAlpha: 0.5,
  id: 'line'
}, {
  coordinates: [[40.749857912194386, -73.96820068359375], [40.741924698522055,-73.9735221862793], [40.735681504432264,-73.97523880004883], [40.7315190495212,-73.97438049316406], [40.729177554196376,-73.97180557250975], [40.72345355209305,-73.97438049316406], [40.719290332250544,-73.97455215454102], [40.71369559554873,-73.97729873657227], [40.71200407096382,-73.97850036621094], [40.71031250340588,-73.98691177368163], [40.71031250340588,-73.99154663085938]],
  type: 'polygon',
  fillAlpha:1,
  fillColor: '#C32C2C',
  strokeColor: '#DDDDD',
  id: 'route'
}]

Immutability

When adding new annotations or modifying existing ones, it's recommended not to mutate the annotations array, but rather treat it as immutable and create a new one with the same objects plus your modifications.

If your annotations array is immutable and you enable annotationsAreImmutable, this enables important performance optimizations when this component is re-rendered.

See the example for an illustration of this.

Mapbox Telemetry (metrics)

If you hide the attribution button, you need to provide the user with a way to opt-out of telemetry. For this, you need to add MGLMapboxMetricsEnabledSettingShownInApp as YES in Info.plist, then create a switch that toggles metrics.

To get the current state of metrics, use Mapbox.getMetricsEnabled().

To enable or disable metrics, use Mapbox.setMetricsEnabled(enabled: boolean).

Offline

There are 3 main methods for interacting with the offline API:

• Mapbox.addOfflinePackForRegion: Creates an offline pack
• Mapbox.getOfflinePacks: Returns an array of all offline packs on the device
• Mapbox.removeOfflinePack: Removes a single pack

Before using them, don't forget to set an access token with Mapbox.setAccessToken(accessToken)

These methods return a promise, but they also accept a callback as the last argument with the signature (err, value) => {}.

Creating a pack

Mapbox.addOfflinePack({
    name: 'test', // required
    type: 'bbox', // required, only type currently supported`
    metadata: { // optional. You can put any information in here that may be useful to you
        date: new Date(),
        foo: 'bar'
    },
    bounds: [ // required. The corners of the bounded rectangle region being saved offline
      latitudeSW, longitudeSW, latitudeNE, longitudeNE
    ],
    minZoomLevel: 10, // required
    maxZoomLevel: 13, // required
    styleURL: Mapbox.mapStyles.emerald // required. Valid styleURL
}).then(() => {
  // Called after the pack has been added successfully
}).catch(err => {
  console.error(err); // Handle error
});

Deleting a pack

To delete a pack, provide the name of the pack to delete.

Mapbox.removeOfflinePack('test')
  .then(info => {
    if (info.deleted) {
      console.log(`Deleted pack named ${info.deleted}`); // The pack has been deleted successfully
    } else {
      console.log('No packs to delete'); // There are no packs named 'test'
    }
  })
  .catch(err => {
    console.error(err); // Handle error
  });

Querying progress

Mapbox.getOfflinePacks()
  .then(packs => {
    // packs is an array of progress objects
  })
  .catch(err => {
    console.error(err); // Handle error
  })

A progress object has the following shape:

{
  name: 'test', // The name this pack was registered with
  metadata, // The value that was previously passed as metadata
  countOfBytesCompleted: 0, // The number of bytes downloaded for this pack
  countOfResourcesCompleted: 0, // The number of tiles that have been downloaded for this pack
  countOfResourcesExpected: 0, // The estimated minimum number of total tiles in this pack
  maximumResourcesExpected: 0 // The estimated maximum number of total tiles in this pack
}

Subscribing to progress notifications

const subscription = Mapbox.addOfflinePackProgressListener(progressObject => {
  // progressObject has the same format as above
});

// Remove the listener when it is not needed anymore
subscription.remove();

Due to high volume, progress notifications are throttled so as not to starve the run loop and make the JS thread unresponsive.

By default, you'll get at most one progress notification per pack each 300 ms.

You can configure this interval with:

Mapbox.setOfflinePackProgressThrottleInterval(milis);

Subscribing to error events

const subscription = Mapbox.addOfflineErrorListener(payload => {
  console.log(`Offline pack named ${payload.name} experienced an error: ${payload.error}`);
});

// Remove the listener when it is not needed anymore
subscription.remove();

const subscription = Mapbox.addOfflineMaxAllowedTilesListener(payload => {
  console.log(`Offline pack named ${payload.name} reached max tiles quota of ${payload.maxTiles} tiles`);
});

// Remove the listener when it is not needed anymore
subscription.remove();

Check out our help page for more information on offline.