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).

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>
  );
}
Note: The map uses free CARTO basemap tiles by default. No API key required. Tiles automatically switch between light and dark themes based on your app's color scheme.
PreviousIntroductionNextCommercial use