Installation

How to install and set up mapcn in your React Native project.

Beta Version: This library requires @maplibre/maplibre-react-native@11.0.0-beta.10, which is currently in beta. Version 11 is used due to its support for the new architecture. Breaking changes may arise.
You can use the mapbox version, which uses stable @rnmapbox/maps

Expo Development Client: MapLibre React Native (and Mabpox) require a development build. They will not work with Expo Go.

Run a development build

Use a development build to run the native map SDK on a simulator or device.

npx expo run:ios

npx expo run:android

Prerequisites

A React Native project with Expo or bare React Native. This component library works best with Expo and requires NativeWind/Uniwind for styling. The component code is the same for both.

Note: The map uses CARTO basemap tiles by default, which are only free for NON-COMMERCIAL use. For cheaper commercial use, check out the Mapbox/Maptiler based version of the component. Tiles automatically switch between light and dark themes based on your app's color scheme.

Install Map Component

There are three versions of the component:

using maplibre with CARTO Basemaps (enterprise pricing for commercial use, free for non-commercial)
using mapbox (free tier - pay after reaching limit)
using maplibre with maptiler maps (free tier - pay after reaching limit)

Install CARTO Basemaps-based map:

npx mapcn-rn add

Install mapbox-based map:

Additionial setup

npx mapcn-rn add --provider=mapbox

Install maptiler-based map:

Additionial setup

npx mapcn-rn add --provider=maptiler

This will add the map component to components/ui/map.tsx in your project.

Check out the commercial use page for more information and additional setup steps.

For the full wrapper CLI flow, including provider selection, see the CLI page.

Configure Permissions

Under plugins, you cannot have both maplibre and rnmapbox packages, and it will throw an error if both are inside the app.

If you plan to use location features, configure permissions for iOS and Android:

Expo (app.json)

<!-- app.json -->
{
  "expo": {
    ...
    "newArchEnabled": true,
    "ios": {
      ...
      "infoPlist": {
        "ITSAppUsesNonExemptEncryption": false,
        "NSAppTransportSecurity": {
          "NSAllowsArbitraryLoads": true
        },
        "NSLocationWhenInUseUsageDescription": "This app needs access to your location to show you on the map.",
        "NSLocationAlwaysAndWhenInUseUsageDescription": "This app needs access to your location to show you on the map."
      }
    },
    "android": {
      ...
      "permissions": [
        "ACCESS_FINE_LOCATION",
        "ACCESS_COARSE_LOCATION"
      ]
    },
    "plugins": [
      ...
      // this will show a warning for no valid plugin, but it is required
      "@maplibre/maplibre-react-native" // "@rnmapbox/maps" if using mapbox version
    ],
    ...
  }
}

Using Bare React Native

iOS (Info.plist)

<!-- ios/YourApp/Info.plist -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to show it on the map</string>

Android (AndroidManifest.xml)

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Usage

Import and use the map component in your screens:

import { Map } from "@/components/ui/map";
import { View } from "react-native";

export default function BasicMapExample() {
  return (
    <View className="h-[500px] rounded-xl overflow-hidden border border-border">
      <Map zoom={12} center={[-122.4194, 37.7749]} />
    </View>
  );
}

PreviousIntroduction NextCLI