Introduction

mapcn-react-native is a registry of map components for Expo and React Native. It gives you a renderer-independent component API while letting you choose MapLibre or Mapbox underneath.

You own the code

mapcn-rn follows the shadcn model: the CLI copies component source into your application. There is no mapcn runtime package between your app and the native renderer. You can read the implementation, change it, and commit it with the rest of your code.

That ownership has a tradeoff. Upgrades are source updates, not opaque package bumps. mapcn-rn diff shows how an installed component differs from its registry version, and an overwrite creates a backup before replacing a locally changed file.

What's in the box

Components. Map with a controlled viewport, markers, popups, and controls for the basics. GeoJSON, polygons, circles, and routes for geometry. Clustering, heatmaps, choropleths, and legends for data. Location tracking, a location puck, and a style switcher for the rest. See the full index.

Two renderers, one API. MapLibre or Mapbox, chosen at setup and swappable later. Where the native SDKs genuinely differ, the docs say so instead of faking parity — see the compatibility matrix.

Basemaps, decoupled from the renderer. CARTO (no API key), MapTiler, Mapbox, or your own style URL. Light and dark styles resolve from the system color scheme by default.

A CLI that tracks what it installed. init sets the project up, add installs components with their dependencies and native permissions, diff shows what you've customized, doctor checks the whole setup, and provider switches basemaps. State lives in a project-local mapcn.json with a hash per file, so an update never silently overwrites your edits.

When to use it

Reach for mapcn-rn when:

• you want a real native vector map. MapLibre and Mapbox render on the GPU through their native SDKs — smooth at 60fps, correct at 10k+ points, with the tile caching and gesture handling users expect from a map.
• you want to own the component, not rent it. The source lands in your repo. Restyle a marker, change how a popup animates, or rewrite a layer's paint properties without waiting on a maintainer or fighting a prop API that doesn't expose what you need.
• you haven't committed to a provider. Start on MapLibre with CARTO for free, no API key, no account. Move to MapTiler or Mapbox later with mapcn-rn provider — the components are re-installed underneath you, but the API your app calls stays the same.
• you want the hard parts already solved. Clustering, heatmaps, choropleths with real scale functions, geodesically-accurate circles, GeoJSON sources, location tracking, and a style switcher — built on native layers and expressions rather than React Native views, so they stay fast at scale.
• you're building anything place-shaped: store locators, delivery and driver tracking, real estate and travel browsing, fleet dashboards, run and ride tracking, coverage and territory maps.

When not to use it

It is probably not the right fit when:

• you're building for the web. These components target React Native's native map SDKs. Use mapcn instead — same idea, built for the web.
• you want a hosted, zero-code map rather than source files owned by your application.

Get started

One command sets up the project and installs the components you pick:

npx mapcn-rn init

See Installation for requirements and native build steps, or read Renderers and providers before choosing your stack.