react-native-maplibre-gl-js

> [!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

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

$3

- 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

$3

- 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

- 3.1. Component basis

$3

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

$3

- 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

$3

- 6.1. Component basis

$3

- 7.1. Component basis

$3

- 8.1. Component basis

🏁 Getting started

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

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

const App = () => {
return (

options={{
style: 'https://tiles.openfreemap.org/styles/liberty',
center: [2.32, 48.86],
zoom: 12,
}}
/>

)
}

export default App
`

📝 Design rationale

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

$3

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

$3

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

---