intermediate
JavaScript
First steps with the Mapbox Maps SDK for React Native
Prerequisite
Familiarity with React Native and JavaScript.

The Mapbox Maps SDK for React Native is a cross platform solution that provides reusable JavaScript components for building mapping and location into Android and iOS apps. This guide will walk you through the basics of working with the Maps SDK for React Native, including how to customize your map, add annotations with callouts, and display a user’s location on a map.

Show user location on Android
React Native app on an Android device
Show user location on iOS
React Native app on an iOS device

Getting started

Before you start building your app, you will need to set up React Native, some Android and iOS development tools, a Mapbox account, and the Mapbox Maps SDK for React Native.

React Native

There are several resources you will need to get React Native up and running if you have not worked with it before. We recommend referring to the React Native Getting started guide using the Building Projects with Native Code option. The demo project in this guide was created using react-native init, a command from the React Native CLI.

Android and iOS tools

To run the application on Android or iOS, you’ll need a few platform-specific resources.

For Android you’ll need:

For iOS you’ll need:

  • Xcode (Mac only). You can download Xcode for free from the Apple App store. Be sure to set up Xcode following the instructions in the React Native Getting started guide.
  • iOS device (Mac only). You will need either a physical iOS device or Simulator (an application that comes with Xcode) to preview your application.

Mapbox

You’ll also need these Mapbox-specific resources before you start developing:

Initialize a map

Once you’ve set up your development environment, created a new React Native project, and installed the Mapbox Maps SDK for React Native, you’re ready to initialize a map in your App.js file.

First, you’ll import the components that you will need. This includes components from React, React Native, and Mapbox. To display a map you’ll need a Mapbox access token. Mapbox uses access tokens to associate requests to API resources with your account. As soon as you have imported Mapbox, you should set your Mapbox access token using Mapbox.setAccessToken().

Then, use the Mapbox.MapView component to initialize your map. The MapView component will add a map to the view, and you can add props to specify some parameters for the map including the map style, zoom level, and center of the map.

Here’s the complete code to display a map:

App.js
import React, { Component } from 'react';
import { StyleSheet, View } from 'react-native';
import Mapbox from '@mapbox/react-native-mapbox-gl';

Mapbox.setAccessToken('<your access token here>');

export default class App extends Component<{}> {
  render() {
    return (
      <View style={styles.container}>
        <Mapbox.MapView
            styleURL={Mapbox.StyleURL.Street}
            zoomLevel={15}
            centerCoordinate={[11.256, 43.770]}
            style={styles.container}>
        </Mapbox.MapView>
      </View>
    );
  }
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

Use either react-native start-android or react-native start-ios to run your application on Android or iOS. You will see a map centered on Florence, Italy.

Initialize a map on Android
Initialize a map on Android
Initialize a map on iOS
Initialize a map on iOS

Change the map style

In the code above, the line styleURL={Mapbox.StyleURL.Street} determines the style of the map. The Maps SDK for React Native provides a set of convenience methods that will return the style URLs of our template styles including:

  • Mapbox.StyleURL.Street
  • Mapbox.StyleURL.Dark
  • Mapbox.StyleURL.Light

You can also set styleURL to a custom style URL from your Mapbox account including one of our designer styles or your own completely custom style made with Mapbox Studio.

Replace the current code defining the styleURL with the line below to change the map style from Mapbox Streets to our Mapbox Dark style.

App.js
styleURL={Mapbox.StyleURL.Dark}

Run your application again, and you will see a dark colored map centered on Florence, Italy.

Change the map style on Android
Change the map style on Android
Change the map style on iOS
Change the map style on iOS

Add an annotation

Next, you’ll add a single annotation to the map and display a callout when the annotation is tapped.

Within export default class App extends Component<{}> { }, create a new function called renderAnnotations (). This function will create a point annotation, specify its location, pull in style properties for the annotation, and determine the contents of a callout.

Add two new items to the StyleSheet: annotationContainer and annotationFill. Add properties to create an orange circle with a white border. You’ll use these to style <View style={styles.annotationContainer}> and <View style={styles.annotationFill} />

Finally, call the renderAnnotation() function when the map is initialized using {this.renderAnnotations()}.

Here’s the complete code to add an annotation to the map:

App.js
import React, { Component } from 'react';
import { StyleSheet, View } from 'react-native';
import Mapbox from '@mapbox/react-native-mapbox-gl';

Mapbox.setAccessToken('<your access token here>');

export default class App extends Component<{}> {

  renderAnnotations () {
    return (
      <Mapbox.PointAnnotation
        key='pointAnnotation'
        id='pointAnnotation'
        coordinate={[11.254, 43.772]}>

        <View style={styles.annotationContainer}>
          <View style={styles.annotationFill} />
        </View>
        <Mapbox.Callout title='Look! An annotation!' />
      </Mapbox.PointAnnotation>
    )
  }

  render() {
    return (
      <View style={styles.container}>
        <Mapbox.MapView
            styleURL={Mapbox.StyleURL.Dark}
            zoomLevel={15}
            centerCoordinate={[11.256, 43.770]}
            style={styles.container}>
            {this.renderAnnotations()}
        </Mapbox.MapView>
      </View>
    );
  }}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  annotationContainer: {
    width: 30,
    height: 30,
    alignItems: 'center',
    justifyContent: 'center',
    backgroundColor: 'white',
    borderRadius: 15,
  },
  annotationFill: {
    width: 30,
    height: 30,
    borderRadius: 15,
    backgroundColor: 'orange',
    transform: [{ scale: 0.6 }],
  }
});

Run your application, and you will see an orange annotation on the map. If you tap on the annotation, a callout will appear.

Add an annotation on Android
Add an annotation on Android
Add an annotation on iOS
Add an annotation on iOS

Display the user’s location

Finally, you’ll display the user’s location on the map. Add another prop to the Mapbox.MapView component: showUserLocation={true}. This will add a blue circle at the user’s location when the map loads.

Here’s the complete code to track and display a user location:

App.js
import React, { Component } from 'react';
import { StyleSheet, View } from 'react-native';
import Mapbox from '@mapbox/react-native-mapbox-gl';

Mapbox.setAccessToken('<your access token here>');

export default class App extends Component<{}> {

  renderAnnotations () {
    return (
      <Mapbox.PointAnnotation
        key='pointAnnotation'
        id='pointAnnotation'
        coordinate={[11.254, 43.772]}>

        <View style={styles.annotationContainer}>
          <View style={styles.annotationFill} />
        </View>
        <Mapbox.Callout title='Look! An annotation!' />
      </Mapbox.PointAnnotation>
    )
  }

  render() {
    return (
      <View style={styles.container}>
        <Mapbox.MapView
            styleURL={Mapbox.StyleURL.Dark}
            zoomLevel={15}
            centerCoordinate={[11.256, 43.770]}
            style={styles.container}
            showUserLocation={true}> 
            {this.renderAnnotations()}
        </Mapbox.MapView>
      </View>
    );
  }
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  annotationContainer: {
    width: 30,
    height: 30,
    alignItems: 'center',
    justifyContent: 'center',
    backgroundColor: 'white',
    borderRadius: 15,
  },
  annotationFill: {
    width: 30,
    height: 30,
    borderRadius: 15,
    backgroundColor: 'orange',
    transform: [{ scale: 0.6 }],
  },
});

Run your application on Android or iOS. You’ll be presented with a dialog box asking for permission to use Location Services. Click Allow.

You won’t see your location on the map until you set a mock user location.

If you are using Simulator for iOS, go to Simulator’s menu bar and select Debug ‣ Location ‣ Custom Location. Enter 43.770 for latitude and 11.256 for longitude.

If you are using an Android virtual device, click the three dots, representing Extended controls, on the toolbar in the emulator. In the Location section, enter 11.256 for longitude, enter 43.770 for latitude, and click Send.

You will see blue dot displaying the user’s location.

Show user location on Android
Show user location on Android
Show user location on iOS
Show user location on iOS

Finished product

You just built a small app with the Mapbox Maps SDK for React Native! You added a Mapbox map to a mobile application, changed the map style, placed an annotation on your map, and displayed the user’s location on it.

Next steps

Check out the Mapbox Maps SDK for React Native documentation on GitHub and explore our React Native example application to see what you can do with the Maps SDK.