Installation

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

Beta Version: This library requires @maplibre/[email protected], 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 npx expo run:ios or npx expo run:android to build and run on a simulator or device.

Prerequisites

A React Native project with Expo or bare React Native. This component library works best with Expo and requires NativeWind for styling.

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 @react-native-reusables/cli@latest add https://mapcn-rn.dev/maps/map.json

Install mapbox-based map:

Additionial setup

npx @react-native-reusables/cli@latest add https://mapcn-rn.dev/maps/map-mapbox.json

Install maptiler-based map:

Additionial setup

npx @react-native-reusables/cli@latest add https://mapcn-rn.dev/maps/map-maptiler.json

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.

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 NextCommercial use