Installation

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

Alpha Version: This library requires @maplibre/maplibre-react-native@11.0.0-alpha.28, which is currently in alpha. Version 11 is used due to its support for the new architecture. Breaking changes may arise.
Expo Development Client: MapLibre React Native requires a development build. It 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.

Install Dependencies

First, install the required packages:

npx expo install @maplibre/maplibre-react-native@11.0.0-alpha.28 expo-location

This installs @maplibre/maplibre-react-native (the map library) and expo-location (for location services).

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

Install Map Component

Run the following command to add the map component:

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

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

Install Maptiler based Map Component for cheaper commercial use

Run the following command to add the map component:

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

Get a Maptiler API key from the Maptiler website.

Maptiler pricing:

  • Free tier: 100,000 requests/month
  • Additional pricing info is available on their pricing page

Add the API key to your environment variables:

# .env
EXPO_PUBLIC_MAPTILER_API_KEY=your_maptiler_api_key_here

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

Configure Permissions

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"
    ],
    ...
  }
}

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>
  );
}
PreviousIntroductionNextCommercial use