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