MapView

MapView backed by Mapbox Native GL. This is the core component that renders the map.

Import

import { MapView } from '@rnmapbox/maps';

Basic Usage

import { MapView, Camera } from '@rnmapbox/maps';

function MyMap() {
  return (
    <MapView
      style={{ flex: 1 }}
      styleURL="mapbox://styles/mapbox/streets-v12"
    >
      <Camera
        centerCoordinate={[-74.006, 40.7128]}
        zoomLevel={14}
      />
    </MapView>
  );
}

Props

projection

'mercator' | 'globe'

The projection used when rendering the map.

styleURL

string

Style URL for map. If none is set, it will default to Mapbox.StyleURL.Street.

<MapView styleURL="mapbox://styles/mapbox/streets-v12" />

styleJSON

string

StyleJSON for map according to TileJSON specs.

preferredFramesPerSecond

number

iOS: The preferred frame rate at which the map view is rendered. The default value adapts based on the device capability.Android: The maximum frame rate at which the map view is rendered, limited by device hardware capability.This property can be set to arbitrary integer values.

zoomEnabled

boolean

Enable or disable zoom gestures on the map.

scrollEnabled

boolean

default:"true"

Enable or disable scroll/pan gestures on the map.

pitchEnabled

boolean

default:"true"

Enable or disable pitch gestures on the map.

maxPitch

number

Maximum allowed pitch in degrees. Mirrors the Mapbox map option maxPitch.

rotateEnabled

boolean

default:"true"

Enable or disable rotation gestures on the map.

attributionEnabled

boolean

default:"true"

Enable or disable attribution on the map.

The Mapbox terms of service require attribution notices to accompany maps using Mapbox-designed styles, OpenStreetMap data, or other Mapbox data. Do not hide this view or remove notices from it.You must also provide users with the option to disable telemetry. For iOS, add MGLMapboxMetricsEnabledSettingShownInApp=YES to your Info.plist.

attributionPosition

{ top?: number, bottom?: number, left?: number, right?: number }

Adds attribution offset. For example, {top: 8, left: 8} will put the attribution button in the top-left corner of the map.By default:

Android: Attribution with information icon (i) on bottom left
iOS: Mapbox logo on bottom left, information icon (i) on bottom right

tintColor

string | number[]

MapView’s tint color.

logoEnabled

boolean

default:"true"

Enable or disable the Mapbox logo on the map.

logoPosition

{ top?: number, bottom?: number, left?: number, right?: number }

Adds logo offset. For example, {top: 8, left: 8} will put the logo in the top-left corner of the map.

compassEnabled

boolean

default:"false"

Enable or disable the compass from appearing on the map.

compassFadeWhenNorth

boolean

default:"false"

Enable or disable the compass fading out when the map is pointing north. V10+ only.

compassPosition

{ top?: number, bottom?: number, left?: number, right?: number }

Adds compass offset. For example, {top: 8, left: 8} will put the compass in the top-left corner of the map. V10+ only.

compassViewPosition

number

Change corner of map the compass starts at:

0: TopLeft
1: TopRight
2: BottomLeft
3: BottomRight

compassViewMargins

{ x: number, y: number }

Add margins to the compass with x and y values.

compassImage

string

A string referencing an image key. Requires an Images component. iOS only, V10+ only.

scaleBarEnabled

boolean

default:"true"

Enable or disable the scale bar from appearing on the map. V10+ only.

scaleBarPosition

{ top?: number, bottom?: number, left?: number, right?: number }

Adds scale bar offset. For example, {top: 8, left: 8} will put the scale bar in the top-left corner of the map. V10+ only.

surfaceView

boolean

default:"true"

Enable or disable use of GLSurfaceView instead of TextureView. Android only.

requestDisallowInterceptTouchEvent

boolean

default:"false"

Experimental: Call requestDisallowInterceptTouchEvent on parent with onTouchEvent. This allows touch interaction to work when embedded into a scroll view. Android only.

localizeLabels

{ locale: string, layerIds?: string[] } | true

Set map’s label locale. V10+ only.

{ locale: "es" } - Localize labels to Spanish
{ locale: "current" } - Localize labels to system locale
true - Equivalent to { locale: "current" }

Optionally specify layerIds to localize only specific layers.

<MapView localizeLabels={{ locale: "es" }} />

gestureSettings

GestureSettings

Gesture configuration to control user touch interaction.

<MapView
  gestureSettings={{
    doubleTapToZoomInEnabled: true,
    pinchZoomEnabled: true,
    rotateEnabled: true,
  }}
/>

GestureSettings Properties:

doubleTapToZoomInEnabled?: boolean - Double tap with one touch to zoom in
doubleTouchToZoomOutEnabled?: boolean - Single tap with two touches to zoom out
pinchPanEnabled?: boolean - Pan/scroll for pinch gesture
pinchZoomEnabled?: boolean - Zoom for pinch gesture
pinchZoomDecelerationEnabled?: boolean - Deceleration animation after pinch-zoom (Android only)
pitchEnabled?: boolean - Pitch gesture enabled
quickZoomEnabled?: boolean - Quick zoom gesture enabled
rotateEnabled?: boolean - Rotate gesture enabled
rotateDecelerationEnabled?: boolean - Deceleration animation after rotate (Android only)
panEnabled?: boolean - Single-touch pan/scroll gesture
panDecelerationFactor?: number - Pan deceleration speed factor
simultaneousRotateAndPinchZoomEnabled?: boolean - Rotation during pinch zoom
zoomAnimationAmount?: number - Zoom level change during double-tap gestures (Android only)

contentInset

number | number[]

Deprecated: Use Camera padding instead.

The distance from the edges of the map view’s frame to the edges of the map view’s logical viewport.

deselectAnnotationOnTap

boolean

default:"false"

Set to true to deselect any selected annotation when the map is tapped. If set to true, you will not receive the onPress event for taps that deselect an annotation.

Events

onPress

(feature: GeoJSON.Feature) => void

Called when a user presses the map.

<MapView
  onPress={(feature) => {
    console.log('Pressed at:', feature.geometry.coordinates);
  }}
/>

onLongPress

(feature: GeoJSON.Feature) => void

Called when a user long presses the map.

onCameraChanged

(state: MapState) => void

Called whenever the map camera is changing. V10+ only, replaces onRegionIsChanging.

<MapView
  onCameraChanged={(state) => {
    console.log('Camera:', state.properties.center, state.properties.zoom);
  }}
/>

onMapIdle

(state: MapState) => void

Called when the map becomes idle after camera movement. V10+ only, replaces onRegionDidChange.

onRegionWillChange

(feature: GeoJSON.Feature<GeoJSON.Point, RegionPayload>) => void

Deprecated: Use onCameraChanged instead. Will be removed in v10.

Called when the displayed map region is about to change.

onRegionIsChanging

(feature: GeoJSON.Feature<GeoJSON.Point, RegionPayload>) => void

Deprecated: Use onCameraChanged instead.

Called when the displayed map region is changing.

onRegionDidChange

(feature: GeoJSON.Feature<GeoJSON.Point, RegionPayload>) => void

Deprecated: Use onMapIdle instead.

Called when the displayed map region finished changing.

onWillStartLoadingMap

() => void

Called when the map is about to start loading a new style.

onDidFinishLoadingMap

() => void

Called when the map has successfully loaded a new style.

onMapLoadingError

() => void

Called when there is an error during map load. V10+ only, replaces onDidFailLoadingMap.

onDidFailLoadingMap

() => void

Deprecated: Use onMapLoadingError instead.

Called when the map has failed to load a new style.

onWillStartRenderingFrame

() => void

Called when the map will start rendering a frame.

onDidFinishRenderingFrame

() => void

Called when the map finished rendering a frame.

onDidFinishRenderingFrameFully

() => void

Called when the map fully finished rendering a frame.

onWillStartRenderingMap

() => void

Called when the map will start rendering.

onDidFinishRenderingMap

() => void

Called when the map finished rendering.

onDidFinishRenderingMapFully

() => void

Called when the map fully finished rendering.

onUserLocationUpdate

(location: Location) => void

Called when the user location is updated.

onDidFinishLoadingStyle

() => void

Called when a style has finished loading.

regionWillChangeDebounceTime

number

default:"10"

The emitted frequency of regionwillchange events in milliseconds.

regionDidChangeDebounceTime

number

default:"500"

The emitted frequency of regiondidchange events in milliseconds.

Methods

To use imperative methods, create a ref:

const mapRef = useRef<MapView>(null);

<MapView ref={mapRef} />

getPointInView()

getPointInView(coordinate: Position): Promise<Position>

Converts a geographic coordinate to a point in the map view’s coordinate system.

const pointInView = await mapRef.current?.getPointInView([-37.817070, 144.949901]);

getCoordinateFromView()

getCoordinateFromView(point: Position): Promise<Position>

Converts a point in the map view’s coordinate system to a geographic coordinate.

const coordinate = await mapRef.current?.getCoordinateFromView([100, 100]);

getVisibleBounds()

getVisibleBounds(): Promise<[Position, Position]>

Returns the coordinate bounds (ne, sw) visible in the viewport.

const visibleBounds = await mapRef.current?.getVisibleBounds();

queryRenderedFeaturesAtPoint()

queryRenderedFeaturesAtPoint(
  coordinate: Position,
  filter?: FilterExpression | [],
  layerIDs?: string[]
): Promise<GeoJSON.FeatureCollection | undefined>

Returns rendered map features that intersect with a given point.

const features = await mapRef.current?.queryRenderedFeaturesAtPoint(
  [30, 40],
  ['==', 'type', 'Point'],
  ['poi-layer']
);

queryRenderedFeaturesInRect()

queryRenderedFeaturesInRect(
  bbox: [number, number, number, number] | [],
  filter?: FilterExpression | [],
  layerIDs?: string[] | null
): Promise<GeoJSON.FeatureCollection | undefined>

Returns rendered map features that intersect with the given rectangle. In v10, passing an empty array queries the entire visible bounds.

const features = await mapRef.current?.queryRenderedFeaturesInRect(
  [30, 40, 20, 10], // [top, right, bottom, left]
  ['==', 'type', 'Point'],
  ['poi-layer']
);

querySourceFeatures()

querySourceFeatures(
  sourceId: string,
  filter?: FilterExpression | [],
  sourceLayerIDs?: string[]
): Promise<GeoJSON.FeatureCollection>

Returns GeoJSON features within a vector tile or GeoJSON source that satisfy the query parameters.

const features = await mapRef.current?.querySourceFeatures(
  'composite',
  ['==', 'type', 'park'],
  ['landuse']
);

takeSnap()

takeSnap(writeToDisk?: boolean): Promise<string>

Takes a snapshot of the map with current tiles and returns a URI to the image.

const uri = await mapRef.current?.takeSnap(true);

getZoom()

getZoom(): Promise<number>

Returns the current zoom level of the map.

const zoom = await mapRef.current?.getZoom();

getCenter()

getCenter(): Promise<Position>

Returns the map’s geographical center point.

const center = await mapRef.current?.getCenter();

clearData()

clearData(): Promise<void>

Clears temporary map data from the data path. Useful to reduce disk usage or clear invalid cache. V10+ only.

queryTerrainElevation()

queryTerrainElevation(coordinate: Position): Promise<number>

Queries elevation at a geographical location. Returns elevation in meters relative to mean sea-level. Returns null if terrain is disabled or data hasn’t loaded.

const elevation = await mapRef.current?.queryTerrainElevation([-122.4194, 37.7749]);

setSourceVisibility()

setSourceVisibility(
  visible: boolean,
  sourceId: string,
  sourceLayerId?: string | null
): void

Sets the visibility of all layers referencing the specified source.

await mapRef.current?.setSourceVisibility(false, 'composite', 'building');

setFeatureState()

setFeatureState(
  featureId: string,
  state: { [k: string]: any },
  sourceId: string,
  sourceLayerId?: string | null
): Promise<void>

Updates the state map of a feature within a style source. Only listed entries are updated; others retain previous values.

await mapRef.current?.setFeatureState(
  'feature-1',
  { hover: true },
  'my-source',
  'my-source-layer'
);

getFeatureState()

getFeatureState(
  featureId: string,
  sourceId: string,
  sourceLayerId?: string | null
): Promise<Record<string, unknown>>

Returns the state map of a feature within a style source.

const state = await mapRef.current?.getFeatureState(
  'feature-1',
  'my-source',
  'my-source-layer'
);

removeFeatureState()

removeFeatureState(
  featureId: string,
  stateKey: string | null,
  sourceId: string,
  sourceLayerId?: string | null
): Promise<void>

Removes entries from a feature state object. If stateKey is null, all properties are removed.

await mapRef.current?.removeFeatureState(
  'feature-1',
  'hover',
  'my-source',
  'my-source-layer'
);

Examples

Basic Map
With Gestures
Globe Projection
With Methods

import { MapView, Camera } from '@rnmapbox/maps';

function BasicMap() {
  return (
    <MapView
      style={{ flex: 1 }}
      styleURL="mapbox://styles/mapbox/streets-v12"
    >
      <Camera
        centerCoordinate={[-74.006, 40.7128]}
        zoomLevel={14}
      />
    </MapView>
  );
}

import { MapView, Camera } from '@rnmapbox/maps';

function MapWithGestures() {
  return (
    <MapView
      style={{ flex: 1 }}
      zoomEnabled={true}
      scrollEnabled={true}
      pitchEnabled={true}
      rotateEnabled={true}
      gestureSettings={{
        doubleTapToZoomInEnabled: true,
        pinchZoomEnabled: true,
      }}
      onPress={(feature) => {
        console.log('Tapped at:', feature.geometry.coordinates);
      }}
    >
      <Camera
        centerCoordinate={[-74.006, 40.7128]}
        zoomLevel={14}
      />
    </MapView>
  );
}

import { MapView, Camera } from '@rnmapbox/maps';

function GlobeMap() {
  return (
    <MapView
      style={{ flex: 1 }}
      projection="globe"
      styleURL="mapbox://styles/mapbox/standard"
    >
      <Camera
        centerCoordinate={[0, 0]}
        zoomLevel={1}
      />
    </MapView>
  );
}

import { useRef } from 'react';
import { MapView, Camera } from '@rnmapbox/maps';
import { Button } from 'react-native';

function MapWithMethods() {
  const mapRef = useRef<MapView>(null);

  const handleSnapshot = async () => {
    const uri = await mapRef.current?.takeSnap(true);
    console.log('Snapshot saved to:', uri);
  };

  const handleGetZoom = async () => {
    const zoom = await mapRef.current?.getZoom();
    console.log('Current zoom:', zoom);
  };

  return (
    <>
      <MapView ref={mapRef} style={{ flex: 1 }}>
        <Camera
          centerCoordinate={[-74.006, 40.7128]}
          zoomLevel={14}
        />
      </MapView>
      <Button title="Take Snapshot" onPress={handleSnapshot} />
      <Button title="Get Zoom" onPress={handleGetZoom} />
    </>
  );
}

Camera - Control the map camera
UserLocation - Show user location
StyleImport - Configure standard style

Core Components

Sources

Layers

Annotations

Location

Assets

Terrain

Offline & Utilities

Modules

​MapView

​Import

​Basic Usage

​Props

​projection

​styleURL

​styleJSON

​preferredFramesPerSecond

​zoomEnabled

​scrollEnabled

​pitchEnabled

​maxPitch

​rotateEnabled

​attributionEnabled

​attributionPosition

​tintColor

​logoEnabled

​logoPosition

​compassEnabled

​compassFadeWhenNorth

​compassPosition

​compassViewPosition

​compassViewMargins

​compassImage

​scaleBarEnabled

​scaleBarPosition

​surfaceView

​requestDisallowInterceptTouchEvent

​localizeLabels

​gestureSettings

​contentInset

​deselectAnnotationOnTap

​Events

​onPress

​onLongPress

​onCameraChanged

​onMapIdle

​onRegionWillChange

​onRegionIsChanging

​onRegionDidChange

​onWillStartLoadingMap

​onDidFinishLoadingMap

​onMapLoadingError

​onDidFailLoadingMap

​onWillStartRenderingFrame

​onDidFinishRenderingFrame

​onDidFinishRenderingFrameFully

​onWillStartRenderingMap

​onDidFinishRenderingMap

​onDidFinishRenderingMapFully

​onUserLocationUpdate

​onDidFinishLoadingStyle

​regionWillChangeDebounceTime

​regionDidChangeDebounceTime

​Methods

​getPointInView()

​getCoordinateFromView()

​getVisibleBounds()

​queryRenderedFeaturesAtPoint()

​queryRenderedFeaturesInRect()

​querySourceFeatures()

​takeSnap()

​getZoom()

​getCenter()

​clearData()

​queryTerrainElevation()

​setSourceVisibility()

​setFeatureState()

​getFeatureState()

​removeFeatureState()

​Examples

MapView

Import

Basic Usage

Props

projection

styleURL

styleJSON

preferredFramesPerSecond

zoomEnabled

scrollEnabled

pitchEnabled

maxPitch

rotateEnabled

attributionEnabled

attributionPosition

tintColor

logoEnabled

logoPosition

compassEnabled

compassFadeWhenNorth

compassPosition

compassViewPosition

compassViewMargins

compassImage

scaleBarEnabled

scaleBarPosition

surfaceView

requestDisallowInterceptTouchEvent

localizeLabels

gestureSettings

contentInset

deselectAnnotationOnTap

Events

onPress

onLongPress

onCameraChanged

onMapIdle

onRegionWillChange

onRegionIsChanging

onRegionDidChange

onWillStartLoadingMap

onDidFinishLoadingMap

onMapLoadingError

onDidFailLoadingMap

onWillStartRenderingFrame

onDidFinishRenderingFrame

onDidFinishRenderingFrameFully

onWillStartRenderingMap

onDidFinishRenderingMap

onDidFinishRenderingMapFully

onUserLocationUpdate

onDidFinishLoadingStyle

regionWillChangeDebounceTime

regionDidChangeDebounceTime

Methods

getPointInView()

getCoordinateFromView()

getVisibleBounds()

queryRenderedFeaturesAtPoint()

queryRenderedFeaturesInRect()

querySourceFeatures()

takeSnap()

getZoom()

getCenter()

clearData()

queryTerrainElevation()

setSourceVisibility()

setFeatureState()

getFeatureState()

removeFeatureState()

Examples

Related Components