[!IMPORTANT] This project is not affiliated with, endorsed by, or sponsored by MapLibre.

Table of contents

• Supported platforms
• Installation
• 📚 Documentation
• 🧪 Examples
  • 1. Map
  • 2. Marker
  • 3. Popup
  • 4. GeoJSONSource
  • 5. ImageSource
  • 6. VideoSource
  • 7. VectorTileSource
  • 8. RasterTileSource
• 🏁 Getting started
• 📝 Design rationale
  • Existing React Native map solutions
  • Architectural approach
• Contributing
• Credits
• License

Supported platforms

| Platform | Status | |----------|--------| | iOS | ✅ | | Android | ✅ | | Web | ❌ |

Installation

npm install react-native-maplibre-gl-js

📚 Documentation

API Reference – Complete TypeScript API documentation.

For library developers – Internal architecture, glossary and design decisions.

🧪 Examples

Several real-world usage scenarios are available, you can explore them in two ways:

• Run the examples as an Expo app to interact with them directly.
• Browse the source code to understand how each feature is implemented (see below the example list).

1. Map

• 1.1. Component basis
• 1.2. Create a camera animation
• 1.3. Use the globe projection
• 1.4. Add a raster tile source directly on map
• 1.5. Use global css styles
• 1.6. Add more velocity to drag pan
• 1.7. Use a native script to enhance performances

2. Marker

• 2.1. Component basis
• 2.2. Animate the coordinate with reanimated
• 2.3. Animate on click with css
• 2.4. Use an detached popup
• 2.5. Use an attached popup
• 2.6. Propagates the events to a parent component
• 2.7. Use a local image

3. Popup

• 3.1. Component basis

4. GeoJSONSource

• 4.1. Component basis
• 4.2. Use a line gradient
• 4.3. Use a local image

5. ImageSource

• 5.1. Component basis
• 5.2. Use an interactive listener
• 5.3. Animate a serie of images 1
• 5.4. Animate a serie of images 2

6. VideoSource

• 6.1. Component basis

7. VectorTileSource

• 7.1. Component basis

8. RasterTileSource

• 8.1. Component basis

🏁 Getting started

The minimal setup to render a MapLibre map in React Native.

import { MapProvider, Map } from 'react-native-maplibre-gl-js';

const App = () => {
  return (
    <MapProvider>
      <Map
        options={{
          style: 'https://tiles.openfreemap.org/styles/liberty',
          center: [2.32, 48.86],
          zoom: 12,
        }}
      />
    </MapProvider>
  )
}

export default App

📝 Design rationale

Explain why I decided to build a new React Native map library instead of using an existing one.

Existing React Native map solutions

Considering tile-based maps, these are the maintained or supported libraries that can be used in React Native. Each has its strengths, and credit goes to their contributors. Still, I have highlighted what I consider to be their main drawbacks.

| Library | Notes | Main Drawbacks | |-----------------------------------|------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | react-native-maps / expo-maps | Overlay custom tiles on Apple Maps (iOS) or Google Maps (iOS/Android). | - On tile loading, the map below (Google Maps or Apple Maps) is visible.- If the map provider is Google Maps (mandatory on the Android platform), an API key is needed to use Google Maps SDK, and therefore its use is billed. | | @rnmapbox/maps | - | - Dependence on Mapbox choices.- On the latest versions, an API key is required (at least on the Android side that drops the MapLibre SDK support), and therefore its use is billed.- To render animated markers or markers with dynamic content and developed visual styles, the use of native views is necessary, and this greatly slows down the application. | | maplibre-react-native | Open source fork of MapBox. | - Being an open source fork of MapBox, the library is years behind (1000+ commits to date) and lacks many features and bug fixes.- The same performance issue with native views as @rnmapbox is also present. |

Architectural approach

To address these drawbacks, two main approaches are possible (as far as I know): either build a library on top of native views using free mobile SDKs (such as MapLibre Native, meaning the effort should instead go into improving maplibre-react-native), or leverage existing web-based map libraries.

The second option is far easier to build and maintain since it relies on a single rendering engine rather than separate iOS and Android SDKs. It also opens the door to fixing performance issues and limitations found in earlier libraries, while enabling more features.

I outline two solutions in this category below, along with the issues they still carry. This library implements the second approach.

| Approach | Description | Main Drawbacks | |----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Remote WebView-based map | Host a map on a web page and access it through a WebView. | - Requires additional infrastructure.- Very sensitive to network latency, and in general, a degraded user experience.- Offline usage is not possible. | | Embedded WebView with bundled MapLibre GL JS | Bundle JS code that runs MapLibre GL JS, enabling two-way communication with React Native, and inject it into a WebView for execution. | - Any interaction between the WebView content and the React Native world is made through message-passing, which can make certain interactions more indirect.- Some objects cannot be serialized and sent between the WebView code and React Native (e.g., HTMLElement).- Some GitHub repositories are implementing this solution, however, no one is actively maintained, and the underlying web libraries are missing key features — good examples being react-native-leaflet-view and @neukolabs/react-native-maplibre-js. |

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

Credits

• MapLibre for providing a free and open source alternative to MapBox.
• OpenFreeMap for providing free tile data in the examples ❤️.

License

MIT