react-native-mapsforge-vtm

React Native components for offline vector maps, built on mapsforge/vtm. Renders OpenStreetMap data from .map files, online raster tiles, MBTiles, hillshading from DEM data, and geometric overlays — all without a network connection (except tile/bitmap layers).

Android only · React Native New Architecture (Fabric + TurboModules) · RN ≥ 0.80.0

Roadmap

ROADMAP.md — Upcoming work prioritizes better markers.

Requirements

• React Native ≥ 0.80.0 with the New Architecture enabled. The library ships pre-generated native code that requires target_compile_reactnative_options (introduced in React Native 0.80.0).
• Android only — ios/generated codegen stubs exist so the New Architecture build doesn't fail, but there is no real iOS implementation.
• newArchEnabled=true in your app's gradle.properties.

Quick Example

import {
  MapContainer,
  LayerBitmapTile,
  LayerScalebar,
} from 'react-native-mapsforge-vtm';

const App = () => (
  <MapContainer
    center={[-77.6, -9.1]}
    zoomLevel={12}
    width={400}
    height={600}
  >
    <LayerBitmapTile
      url="https://tile.openstreetmap.org/{Z}/{X}/{Y}.png"
      zoomMax={18}
    />
    <LayerScalebar />
  </MapContainer>
);

Full documentation → — API reference covering components, hooks, utilities, debug tools, and advanced topics.

Installation

yarn add react-native-mapsforge-vtm

See the Installation Guide for prerequisites, Android setup, and build configuration.

Examples

The example app includes runnable examples across several categories:

Category	Examples
layers	basic, mapsforge, mbtiles-bitmap, hillshading, canvas-adapter, layer-shapes, coastlines, path-jts, markers
mapControls	pan-zoom, fit-bounds, fly-ease, viewport-orientation, trigger, multi-map, reanimated-overlay
gestures	tap-events, layer-order-verification, many-layers, many-shapes, mixed-grouping, shared-layer-grouping, elevation-enrichment
api	mercator-math, viewport-bbox, map-handle-registry, gnss-track-recording

To run the example app:

yarn install
yarn example start      # start Metro (keep running in a separate terminal)
yarn example android    # build & run on device/emulator

Where to get maps

• Vector maps (mapsforge V5 .map): openandromaps.org
• Raster overview maps (MBTiles): openandromaps.org — general maps
• Digital elevation models (.hgt at 3 arc-second): viewfinderpanoramas.org

Components

Component	Description
MapContainer	Root map view (Fabric component)
LayerMapsforge	Offline vector maps from .map files
LayerBitmapTile	Online raster tiles (OSM, custom)
LayerMBTilesBitmap	Offline raster from MBTiles
LayerHillshading	Shaded relief from DEM (.hgt) data
LayerPath	Shared-layer paths for bulk rendering (50–1000+)
LayerPathJts	Dedicated paths with JTS features and guaranteed z-order
LayerShape	Geometric shapes (polygons, circles, rectangles, etc.)
LayerScalebar	Map scale bar
LayerMarker / Marker	Marker container + individual markers
SharedLayer	Collapse same-type children into shared native layer fragments
ReindexScope	Signal layer reorder to the native stack

Hooks

Hook	Description
useMap()	Imperative map control (pan, zoom, animate, fly, fitBounds, altitude/elevation queries)
useMapEventInterval()	Poll map events at a fixed interval
useViewportBbox()	Tile-snapped viewport bounding box with dedup
useRenderStyleOptions()	Read render-theme style menu options

Reanimated

Import from react-native-mapsforge-vtm/reanimated for worklet-based map utilities. Requires react-native-reanimated >= 3.0.0 (optional peer dependency).

Export	Description
useMapPosition()	Reanimated shared values for map center, zoom, bearing, tilt — zero bridge crossings with native bridge activated
useMapOverlay()	Worklet-based overlay positioning (lat/lng → screen coordinates)
toScreenPosition() / fromScreenPosition()	Mercator ↔ screen coordinate conversion callable from worklets

See Performance for the four-tier consumption pattern guide and native bridge activation setup.

Utilities

Export	Description
enrichCoordinatesWithElevation()	Batch-enrich coordinate arrays with SRTM elevation data
createMapHandle() / createMapHandleRegistry()	Non-React imperative map control factories (for Redux thunks, services, etc.)
Mercator math	Non-worklet projection, tile, and screen-coordinate utilities
GNSS filter	Native GNSS track-recording with DEM altitude resolution
CanvasAdapterModule	Global text/line/symbol scale configuration

Debug tools

Tool	Description
useLayerDebugInfo()	Live layer-tree introspection hook
LayerDebugTree	Visual debug overlay component

Resources

• Documentation — Full API reference, guides, and advanced topics
• Extending the library — Build custom layer-type extensions (JS-only, TurboModule, or vtm-shadowing). Use the "ext-plan" OpenCode skill to scaffold new extensions.
• Performance — Scaling guidance, map position consumption patterns, and reanimated native bridge setup
• Naming conventions and terminology — Inclusive language conventions used in this project
• Known Issues — Current bugs, limitations, and workarounds

Contributing

Contributions welcome. Report issues or suggest features, or fork the repository and make pull requests.

License

MIT

Apps using react-native-mapsforge-vtm

This library was built as part of straymap and later extracted as a standalone, reusable package so anyone can pick it up and use it in their own projects.

Another running app is the example app, included in this repository.

Working extensions

• react-native-mapsforge-vtm-ext-path-color-ramp — Color-ramp path rendering via vtm-shadowing

Credits

This library is a React Native wrapper around mapsforge/vtm. All credit for the map rendering engine goes to the mapsforge and vtm projects.

Runtime dependencies

JavaScript (bundled with the library):

• lodash-es — tree-shakeable utility functions

Native (Android) — bundled via Gradle:

• vtm (0.29.0) — the rendering engine, plus vtm-android, vtm-themes, vtm-jts, vtm-http, vtm-mvt, vtm-android-mvt, and vtm-hillshading
• mapsforge (0.29.0) — map file reader (mapsforge-core, mapsforge-map, mapsforge-map-android)
• JTS Topology Suite (jts-core:1.20.0) — geometry engine for path and shape layers
• AndroidSVG — SVG rendering for vtm
• OkHttp / Okio — HTTP client for online tile layers
• Protocol Buffers (protobuf-java 3.x) — MVT/vector tile decoding
• Mapbox Vector Tile — Java — MVT tile parsing

Dev dependencies

• react-native-builder-bob — build tooling (codegen, module bundling, type generation)
• keep-a-changelog — CHANGELOG.md maintenance