File: README.md

react-map-gl | [Docs](https://visgl.github.io/react-map-gl)

react-map-gl is a suite of React components designed to provide a React API for mapbox-gl or maplibre-gl. More information in the online documentation.

See our Design Philosophy.

Installation

Using react-map-gl requires react >= 16.3.

# Using Maplibre
npm install react-map-gl maplibre-gl

# Using Mapbox
npm install react-map-gl mapbox-gl

Example

// Using Maplibre
import * as React from 'react';
import Map from 'react-map-gl/maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

function App() {
  return (
    <Map
      initialViewState={{
        longitude: -122.4,
        latitude: 37.8,
        zoom: 14
      }}
      style={{width: 600, height: 400}}
      mapStyle="https://api.maptiler.com/maps/streets/style.json?key=<Maptiler access token>"
    />
  );
}

// Using Mapbox
import * as React from 'react';
import Map from 'react-map-gl/mapbox';
import 'mapbox-gl/dist/mapbox-gl.css';

function App() {
  return (
    <Map
      // https://visgl.github.io/react-map-gl/docs/get-started/mapbox-tokens
      mapboxAccessToken="<Mapbox access token>"
      initialViewState={{
        longitude: -100,
        latitude: 40,
        zoom: 3.5
      }}
      style={{width: 600, height: 400}}
      mapStyle="mapbox://styles/mapbox/streets-v9"
    />
  );
}

Learn more with in our Getting Started guide.

Contribute

See contribution guide.

Attributions

react-map-gl is part of vis.gl, an OpenJS Foundation project.

Development is also supported by

File: docs/api-reference/maplibre/attribution-control.md

AttributionControl

React component that wraps maplibre-gl's AttributionControl class.

tsx

import * as React from 'react';
import {Map, AttributionControl} from 'react-map-gl/maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

function App() {
  return <Map
    initialViewState={{
      longitude: -100,
      latitude: 40,
      zoom: 3.5
    }}
    mapStyle="https://demotiles.maplibre.org/style.json"
    // disable the default attribution
    attributionControl={false}
  >
    <AttributionControl customAttribution="Map design by me" />
  </Map>;
}

Properties

Reactive Properties

`style`: CSSProperties {#style}

CSS style override that applies to the control's container.

Other Properties

The properties in this section are not reactive. They are only used when the component first mounts.

Any options supported by the AttributionControl class, such as

compact
customAttribution

Plus the following:

`position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}

Default: 'bottom-right'

Placement of the control relative to the map.

Source

attribution-control.ts

File: docs/api-reference/maplibre/fullscreen-control.md

FullscreenControl

React component that wraps maplibre-gl's FullscreenControl class.

tsx

import * as React from 'react';
import {Map, FullscreenControl} from 'react-map-gl/maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

function App() {
  return <Map
    initialViewState={{
      longitude: -100,
      latitude: 40,
      zoom: 3.5
    }}
    mapStyle="https://demotiles.maplibre.org/style.json"
  >
    <FullscreenControl />
  </Map>;
}

Properties

Reactive Properties

`style`: CSSProperties {#style}

CSS style override that applies to the control's container.

Other Properties

The properties in this section are not reactive. They are only used when the component first mounts.

`containerId`: string {#containerid}

Id of the DOM element which should be made full screen. By default, the map container element will be made full screen.

`position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}

Default: 'top-right'

Placement of the control relative to the map.

Source

fullscreen-control.ts

File: docs/api-reference/maplibre/geolocate-control.md

GeolocateControl

React component that wraps maplibre-gl's GeolocateControl class.

tsx

import * as React from 'react';
import {Map, GeolocateControl} from 'react-map-gl/maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

function App() {
  return <Map
    initialViewState={{
      longitude: -100,
      latitude: 40,
      zoom: 3.5
    }}
    mapStyle="https://demotiles.maplibre.org/style.json"
  >
    <GeolocateControl />
  </Map>;
}

Properties

Reactive Properties

`style`: CSSProperties {#style}

CSS style override that applies to the control's container.

Callbacks

`onGeolocate`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#ongeolocate}

Called on each Geolocation API position update that returned as success.

`onError`: (evt: [GeolocateErrorEvent](./types.md#geolocateerrorevent)) => void {#onerror}

Called on each Geolocation API position update that returned as an error.

`onOutOfMaxBounds`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#onoutofmaxbounds}

Called on each Geolocation API position update that returned as success but user position is out of map maxBounds.

`onTrackUserLocationStart`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationstart}

Called when the GeolocateControl changes to the active lock state.

`onTrackUserLocationEnd`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationend}

Called when the GeolocateControl changes to the background state.

Other Properties

The properties in this section are not reactive. They are only used when the component first mounts.

Any options supported by the GeolocateControl class, such as

positionOptions
fitBoundsOptions
trackUserLocation
showAccuracyCircle
showUserLocation

Plus the following:

`position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}

Default: 'bottom-right'

Placement of the control relative to the map.

Methods

The underlying native GeolocateControl instance is accessible via a React ref hook.
You may use it to call any imperative methods:

tsx

import * as React from 'react';
import {useRef, useEffect} from 'react';
import {Map, GeolocateControl} from 'react-map-gl/maplibre';
import type * as maplibregl from 'maplibre-gl';

function App() {
  const geoControlRef = useRef<maplibregl.GeolocateControl>();

  useEffect(() => {
    // Activate as soon as the control is loaded
    geoControlRef.current?.trigger();
  }, [geoControlRef.current]);

  return <Map>
    <GeolocateControl ref={geoControlRef} />
  </Map>;
}

Source

geolocate-control.ts

File: docs/api-reference/maplibre/layer.md

Layer

This component allows apps to create a map layer using React.

tsx

import * as React from 'react';
import {Map, Layer} from 'react-map-gl/maplibre';
import type {FillLayer} from 'react-map-gl/maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

const parkLayer: FillLayer = {
  id: 'landuse_park',
  type: 'fill',
  source: 'vector',
  'source-layer': 'landuse',
  filter: ['==', 'class', 'park'],
  paint: {
    'fill-color': '#4E3FC8'
  }
};

function App() {
  return <Map
    initialViewState={{
      longitude: -122.4,
      latitude: 37.8,
      zoom: 14
    }}
    mapStyle="https://demotiles.maplibre.org/style.json"
  >
    <Layer {...parkLayer} />
  </Map>;
}

Properties

The props provided to this component should be conforming to the Maplibre layer specification.

When props change shallowly, the component will perform style diffing to update the layer. Avoid defining constant objects/arrays inline may help performance.

Identity Properties

Once a <Layer> is mounted, the following props should not change. If you add/remove multiple JSX layers dynamically, make sure you use React's key prop to give each element a stable identity.

`id`: string {#id}

Unique identifier of the layer. If not provided, a default id will be assigned.

`type`: string {#type}

Required. Type of the layer.

Options

`beforeId`: string {#beforeid}

The ID of an existing layer to insert this layer before. If this prop is omitted, the layer will be appended to the end of the layers array. This is useful when using dynamic layers with a map style from a URL.

Note that layers are added by the order that they mount. They are NOT reordered later if their relative positions in the JSX tree change. If dynamic reordering is desired, you should manipulate beforeId for consistent behavior.

`source`: string {#source}

source is required by some layer types in the Mapbox style specification. If <Layer> is used as the immediate child of a Source component, this prop will be overwritten by the id of the parent source. If the <Layer/> component is not an immediate descendant of , e.g wrapped inside a helper component, source property needs to be provided same as the id of the component for the <Layer/> component to show.

Source

layer.ts

File: docs/api-reference/maplibre/logo-control.md

LogoControl

React component that wraps maplibre-gl's LogoControl class.

tsx

import * as React from 'react';
import {Map, LogoControl} from 'react-map-gl/maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

function App() {
  return <Map
    initialViewState={{
      longitude: -100,
      latitude: 40,
      zoom: 3.5
    }}
    mapStyle="https://demotiles.maplibre.org/style.json"
  >
    <LogoControl />
  </Map>;
}

Properties

Reactive Properties

`style`: CSSProperties {#style}

CSS style override that applies to the control's container.

Other Properties

The properties in this section are not reactive. They are only used when the component first mounts.

Any options supported by the LogoControl class, such as

compact

Plus the following:

`position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}

Default: 'top-right'

Placement of the control relative to the map.

Source

logo-control.ts

File: docs/api-reference/maplibre/map.md

default (Map)

React component that wraps maplibre-gl's Map class. This is also the default export from react-map-gl/maplibre.

tsx

import * as React from 'react';
import {Map} from 'react-map-gl/maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

function App() {
  return (
    <Map
      initialViewState={{
        longitude: -122.4,
        latitude: 37.8,
        zoom: 14
      }}
      style={{width: 600, height: 400}}
      mapStyle="https://demotiles.maplibre.org/style.json"
    />
  );
}

Properties

Aside from the props listed below, the Map component supports all options of the Map class constructor. Beware that this is not an exhaustive list of all props. Different base map libraries may offer different options and default values. When in doubt, refer to your base map library's documentation.

Layout options

`id`: string {#id}

Map container id.

`style`: CSSProperties {#style}

Default: {position: 'relative', width: '100%', height: '100%'}

Map container CSS.

`cursor`: string {#cursor}

Default: 'auto'

The current cursor type.

Styling options

`light`: [Light](./types.md#light) {#light}

Light properties of the style. Must conform to the Light Style Specification.

`mapStyle`: [MapStyle](./types.md#mapstyle) | string | Immutable {#mapstyle}

Default: (empty style)

The map's Maplibre style. This must be an a JSON object conforming to the schema described in the MapLibre Style Specification, or a URL to such JSON.

`projection`: string | [Projection](./types.md#projection) {#projection}

Default: 'mercator'

The projection the map should be rendered in. See Projection Specification.

`renderWorldCopies`: boolean {#renderworldcopies}

Default: true

If true, multiple copies of the world will be rendered, when zoomed out.

`sky`: [Sky](./types.md#sky) {#sky}

The sky property of the style. Must conform to the Sky Style Specification.

`styleDiffing`: boolean {#stylediffing}

Default: true

Enable diffing when mapStyle changes. If false, force a 'full' update, removing the current style and building the given one instead of attempting a diff-based update.

`terrain`: [Terrain](./types.md#terrain)|null {#terrain}

Terrain property of the style. Must conform to the Terrain Style Specification.
If null is provided, removes terrain from the map.

Camera options

`initialViewState`: object {#initialviewstate}

The initial view state of the map. If specified, longitude, latitude, zoom etc. in props are ignored when constructing the map. Only specify initialViewState if Map is being used as an uncontrolled component. See state management for examples.

bounds: LngLatBoundsLike - The initial bounds of the map. If specified, it overrides the longitude, latitude and zoom options. Default null.
fitBoundsOptions - An object to use only when setting the bounds option. Default null.
- fitBoundsOptions.offset: PointLike
- fitBoundsOptions.minZoom: number
- fitBoundsOptions.maxZoom: number
- fitBoundsOptions.padding: PaddingOptions
longitude: number - The initial longitude of the map center. Default 0.
latitude: number - The initial latitude of the map center. Default 0.
zoom: number - The initial zoom level. Default 0.
pitch: number - The initial pitch (tilt) of the map. Default 0.
bearing: number - The initial bearing (rotation) of the map. Default 0.

`longitude`: number {#longitude}

The longitude of the map center.

`latitude`: number {#latitude}

The latitude of the map center.

`zoom`: number {#zoom}

The zoom level of the map.

`pitch`: number {#pitch}

The initial pitch (tilt) of the map, measured in degrees away from the plane of the screen (0-85).

`bearing`: number {#bearing}

The initial bearing (rotation) of the map, measured in degrees counter-clockwise from north.

`padding`: [PaddingOptions](./types.md#paddingoptions) {#padding}

Default: null

The padding in pixels around the viewport.

`minZoom`: number {#minzoom}

Default: 0

The minimum zoom level of the map (0-24).

`maxZoom`: number {#maxzoom}

Default: 22

The maximum zoom level of the map (0-24).

`minPitch`: number {#minpitch}

Default: 0

The minimum pitch of the map (0-85).

`maxPitch`: number {#maxpitch}

Default: 60

The maximum pitch of the map (0-85).

`maxBounds`: [LngLatBoundsLike](./types.md#lnglatboundslike) {#maxbounds}

Default: null

If set, the map is constrained to the given bounds.

Input handler options

`boxZoom`: boolean {#boxzoom}

Default: true

If true, the "box zoom" interaction is enabled. See BoxZoomHandler.

`doubleClickZoom`: boolean {#doubleclickzoom}

Default: true

If true, the "double click to zoom" interaction is enabled. See DoubleClickZoomHandler.

`dragRotate`: boolean {#dragrotate}

Default: true

If true, the "drag to rotate" interaction is enabled. See DragRotateHandler.

`dragPan`: boolean | Object {#dragpan}

Default: true

If true, the "drag to pan" interaction is enabled. Optionally accept an object value that is the options to DragPanHandler.

`keyboard`: boolean {#keyboard}

Default: true

If true, keyboard shortcuts are enabled. See KeyboardHandler.

`scrollZoom`: boolean | Object {#scrollzoom}

Default: true

If true, the "scroll to zoom" interaction is enabled. Optionally accept an object value that is the options to ScrollZoomHandler.

`touchPitch`: boolean | Object {#touchpitch}

Default: true

If true, the "drag to pitch" interaction is enabled. Optionally accept an object value that is the options to TwoFingersTouchPitchHandler.

`touchZoomRotate`: boolean | Object {#touchzoomrotate}

Default: true

If true, the "pinch to rotate and zoom" interaction is enabled. Optionally accept an object value that is the options to TwoFingersTouchZoomRotateHandler.

`interactiveLayerIds`: string[] {#interactivelayerids}

Default: null

The id(s) of style layer(s).

If specified, pointer event (mousemove, click etc.) listeners will be triggered only if its location is within a visible feature in these layers, and the event will have a features property containing an array of the matching features.

If not specified, pointer event listeners will be triggered by a corresponding event happening anywhere on the map, and the event will not have a features property.

See the Callbacks section for affected events.

Callbacks

`onResize`: (event: [MapEvent](./types.md#mapevent)) => void {#onresize}

Called when the map has been resized.

`onLoad`: (event: [MapEvent](./types.md#mapevent)) => void {#onload}

Called after all necessary resources have been downloaded and the first visually complete rendering of the map has occurred.

`onRender`: (event: [MapEvent](./types.md#mapevent))) => void {#onrender}

Called whenever the map is drawn to the screen.

`onIdle`: (event: [MapEvent](./types.md#mapevent))) => void {#onidle}

Called after the last frame rendered before the map enters an "idle" state:

No camera transitions are in progress
All currently requested tiles have loaded
All fade/transition animations have completed

`onRemove`: (event: [MapEvent](./types.md#mapevent))) => void {#onremove}

Called when the map has been removed.

`onError`: (event: [ErrorEvent](./types.md#errorevent)) => void {#onerror}

Default: evt => console.error(evt.error)

Called when an error occurs.

`onMouseDown`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmousedown}

Called when a pointing device (usually a mouse) is pressed within the map.

If interactiveLayerIds is specified, the event will contain an additional features field that contains features under the cursor from the specified layer.

`onMouseUp`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseup}

Called when a pointing device (usually a mouse) is released within the map.

If interactiveLayerIds is specified, the event will contain an additional features field that contains features under the cursor from the specified layer.

`onMouseOver`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseover}

Called when a pointing device (usually a mouse) is moved within the map. As you move the cursor across a web page containing a map, the event will fire each time it enters the map or any child elements.

`onMouseEnter`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseenter}

Called when a pointing device (usually a mouse) enters a visible portion of the layer(s) specified by interactiveLayerIds from outside that layer or outside the map canvas.

`onMouseMove`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmousemove}

Called when a pointing device (usually a mouse) is moved while the cursor is inside the map. As you move the cursor across the map, the event will fire every time the cursor changes position within the map.

If interactiveLayerIds is specified, the event will contain an additional features field that contains features under the cursor from the specified layer.

`onMouseLeave`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseleave}

Called when a pointing device (usually a mouse) leaves a visible portion of the layer(s) specified by interactiveLayerIds or moves from the layer to outside the map canvas.

`onMouseOut`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseout}

Called when a point device (usually a mouse) leaves the map's canvas.

`onClick`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onclick}

Called when a pointing device (usually a mouse) is pressed and released at the same point on the map.

If interactiveLayerIds is specified, the event will contain an additional features field that contains features under the cursor from the specified layer.

`onDblClick`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#ondblclick}

Called when a pointing device (usually a mouse) is pressed and released twice at the same point on the map in rapid succession.

If interactiveLayerIds is specified, the event will contain an additional features field that contains features under the cursor from the specified layer.

`onContextMenu`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#oncontextmenu}

Called when the right button of the mouse is clicked or the context menu key is pressed within the map.

If interactiveLayerIds is specified, the event will contain an additional features field that contains features under the cursor from the specified layer.

`onWheel`: (event: [MapWheelEvent](./types.md#mapwheelevent)) => void {#onwheel}

Called when a wheel event occurs within the map.

`onTouchStart`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchstart}

Called when a touchstart event occurs within the map.

If interactiveLayerIds is specified, the event will contain an additional features field that contains features under the cursor from the specified layer.

`onTouchEnd`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchend}

Called when a touchend event occurs within the map.

If interactiveLayerIds is specified, the event will contain an additional features field that contains features under the cursor from the specified layer.

`onTouchMove`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchmove}

Called when a touchmove event occurs within the map.

If interactiveLayerIds is specified, the event will contain an additional features field that contains features under the cursor from the specified layer.

`onTouchCancel`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchcancel}

Called when a touchcancel event occurs within the map.

If interactiveLayerIds is specified, the event will contain an additional features field that contains features under the cursor from the specified layer.

`onMoveStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmovestart}

Called just before the map begins a transition from one view to another.

`onMove`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmove}

Called repeatedly during an animated transition from one view to another.

When Map is used as a controlled component, event.viewState reflects the view state that the camera "proposes" to move to, as a result of either user interaction or methods such as flyTo. The camera does not actually change until the application updates the view state props (longitude, latitude, zoom etc.).
See state management for examples.

`onMoveEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmoveend}

Called just after the map completes a transition from one view to another.

`onDragStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#ondragstart}

Called when a "drag to pan" interaction starts.

`onDrag`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#ondrag}

Called repeatedly during a "drag to pan" interaction.

`onDragEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#ondragend}

Called when a "drag to pan" interaction ends.

`onZoomStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onzoomstart}

Called just before the map begins a transition from one zoom level to another.

`onZoom`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onzoom}

Called repeatedly during an animated transition from one zoom level to another.

When Map is used as a controlled component, event.viewState.zoom reflects the zoom that the camera "proposes" to change to, as a result of either user interaction or methods such as flyTo. The camera does not actually change until the application updates the zoom prop.

`onZoomEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onzoomend}

Called just after the map completes a transition from one zoom level to another.

`onRotateStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onrotatestart}

Called just before the map begins a transition from one bearing (rotation) to another.

`onRotate`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onrotate}

Called repeatedly during an animated transition from one bearing (rotation) to another.

When Map is used as a controlled component, event.viewState.bearing reflects the zoom that the camera "proposes" to change to, as a result of either user interaction or methods such as flyTo. The camera does not actually change until the application updates the bearing prop.

`onRotateEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onrotateend}

Called just after the map completes a transition from one bearing (rotation) to another.

`onPitchStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onpitchstart}

Called just before the map begins a transition from one pitch (tilt) to another.

`onPitch`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onpitch}

Called repeatedly during an animated transition from one pitch (tilt) to another.

When Map is used as a controlled component, event.viewState.pitch reflects the zoom that the camera "proposes" to change to, as a result of either user interaction or methods such as flyTo. The camera does not actually change until the application updates the pitch prop.

`onPitchEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onpitchend}

Called just after the map completes a transition from one pitch (tilt) to another.

`onBoxZoomStart`: (event: [MapBoxZoomEvent](./types.md#mapboxzoomevent)) => void {#onboxzoomstart}

Called when a "box zoom" interaction starts.

`onBoxZoomEnd`: (event: [MapBoxZoomEvent](./types.md#mapboxzoomevent)) => void {#onboxzoomend}

Called when a "box zoom" interaction ends.

`onBoxZoomCancel`: (event:[MapBoxZoomEvent](./types.md#mapboxzoomevent)) => void {#onboxzoomcancel}

Called when the user cancels a "box zoom" interaction, or when the bounding box does not meet the minimum size threshold.

`onData`: (event: [MapStyleDataEvent](./types.md#mapstyledataevent) | [MapSourceDataEvent](./types.md#mapsourcedataevent)) => void {#ondata}

Called when any map data loads or changes. See MapDataEvent for more information.

`onStyleData`: (event: [MapStyleDataEvent](./types.md#mapstyledataevent)) => void {#onstyledata}

Called when the map's style loads or changes. See MapDataEvent for more information.

`onSourceData`: (event: [MapSourceDataEvent](./types.md#mapsourcedataevent)) => void {#onsourcedata}

Called when one of the map's sources loads or changes, including if a tile belonging to a source loads or changes. See MapDataEvent for more information.

Other options

The following props, along with any options of the Map class not listed above, can be specified to construct the underlying Map instance.

Note: props in this section are not reactive. They are only used once when the Map instance is constructed.

`mapLib`: any {#maplib}

Default:

import('maplibre-gl')

Specify the underlying base map library for the Map component. The value can be provided with several options:

By module import (and embedding in the final bundle):

tsx

import * as React from 'react';
import {Map} from 'react-map-gl/maplibre';
import * as maplibregl from 'maplibre-gl';

function App() {
  return <Map mapLib={maplibregl} />;
}

By dynamic import (thus enable bundle splitting):

tsx

import * as React from 'react';
import {Map} from 'react-map-gl/maplibre';

function App() {
  return <Map mapLib={import('maplibre-gl')} />;
}

Or to load a pre-bundled version of the library:

html title="index.html"

<script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js" ></script>

tsx title="app.tsx"

import * as React from 'react';
import {Map} from 'react-map-gl/maplibre';

function App() {
  return <Map mapLib={window.maplibregl} />;
}

`maxParallelImageRequests`: number {#maxparallelimagerequests}

Default: 16

The maximum number of images (raster tiles, sprites, icons) to load in parallel.

`reuseMaps`: boolean {#reusemaps}

Default: false

By default, every time a map component is unmounted, all internal resources associated with the underlying Map instance are released. If the map gets mounted again, a new Map instance is constructed.

If reuseMaps is set to true, when a map component is unmounted, the underlying Map instance is retained in memory. The next time a map component gets mounted, the saved instance is reused. This behavior may be desirable if an application frequently mounts/unmounts map(s), for example in a tabbed or collapsable UI, and wants to avoid recreating the Map and its data cache triggered by initialization.

Note that since some map options cannot be modified after initialization, when reusing maps, only the reactive props and initialViewState of the new component are respected.

`RTLTextPlugin`: string | object {#rtltextplugin}

pluginUrl: string URL to the plugin JS file.
lazy: boolean When true, the plugin is only loaded when the map first encounters Hebrew or Arabic text. Default true.

Sets the map's RTL text plugin via setRTLTextPlugin. Can be used with mapbox-gl-rtl-text. Necessary for supporting the Arabic and Hebrew languages, which are written right-to-left.

`workerCount`: number {#workercount}

Default: 2

The number of web workers instantiated on a page with maplibre-gl maps.

`workerUrl`: string {#workerurl}

Provides an interface for loading maplibre-gl's WebWorker bundle from a self-hosted URL. MapLibre GL JS v6 applications that use a bundler must configure the worker before rendering a map. Follow MapLibre's installation instructions to generate the appropriate worker URL for your bundler.

Methods

Imperative methods are accessible via a React ref or the useMap hook.

tsx

import * as React from 'react';
import {useRef, useCallback} from 'react';
import {Map} from 'react-map-gl/maplibre';
import type {MapRef} from 'react-map-gl/maplibre';

function App() {
  const mapRef = useRef<MapRef>();

  const onMapLoad = useCallback(() => {
    mapRef.current.on('move', () => {
      // do something
    });
  }, []);

  return <Map ref={mapRef} onLoad={onMapLoad} ... />;
}

The MapRef object exposes Map methods that are safe to call without breaking the React bindings. For example, setStyle() is hidden from the ref object, because the style is supposed to be changed by updating the mapStyle prop. Calling the method directly may cause the the React prop to mismatch with the underlying state, and lead to unexpected behaviors.

You can still access the hidden members via getMap():

`getMap()` {#getmap}

Returns the native Map instance associated with this component.

Source

map.tsx

File: docs/api-reference/maplibre/map-provider.md

MapProvider

A Context.Provider that facilitates map operations outside of the component that directly renders a Map.

The component should wrap all nodes in which you may want to access the maps:

tsx

import {MapProvider} from 'react-map-gl/maplibre';

function Root() {
  return (
    <MapProvider>
      {
        // Application tree, somewhere one or more <Map /> component(s) are rendered
      }
    </MapProvider>
  );
}

See useMap for more information.

Source

use-map.tsx

File: docs/api-reference/maplibre/marker.md

Marker

React component that wraps maplibre-gl's Marker class.

tsx

import * as React from 'react';
import {Map, Marker} from 'react-map-gl/maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

function App() {
  return <Map
    initialViewState={{
      longitude: -100,
      latitude: 40,
      zoom: 3.5
    }}
    mapStyle="https://demotiles.maplibre.org/style.json"
  >
    <Marker longitude={-100} latitude={40} anchor="bottom" >
      
    </Marker>
  </Map>;
}

If Marker is mounted with child components, then its content will be rendered to the specified location. If it is mounted with no content, then a default marker will be used.

Properties

Reactive Properties

`draggable`: boolean {#draggable}

Default: false

If true, the marker is able to be dragged to a new position on the map.

`latitude`: number {#latitude}

Required. The latitude of the anchor location.

`longitude`: number {#longitude}

Required. The longitude of the anchor location.

`offset`: [PointLike](./types.md#pointlike) {#offset}

Default: null

The offset in pixels as a PointLike object to apply relative to the element's center. Negatives indicate left and up.

`pitchAlignment`: 'map' | 'viewport' | 'auto' {#pitchalignment}

Default: 'auto'

map aligns the Marker to the plane of the map.
viewport aligns the Marker to the plane of the viewport.
auto automatically matches the value of rotationAlignment.

An instance of the Popup class to attach to this marker. If undefined or null, any popup set on this Marker instance is unset.

`rotation`: number {#rotation}

Default: 0

The rotation angle of the marker in degrees, relative to its rotationAlignment setting. A positive value will rotate the marker clockwise.

`rotationAlignment`: 'map' | 'viewport' | 'auto' {#rotationalignment}

Default: 'auto'

map aligns the Marker's rotation relative to the map, maintaining a bearing as the map rotates.
viewport aligns the Marker's rotation relative to the viewport, agnostic to map rotations.
auto is equivalent to viewport.

`style`: CSSProperties {#style}

CSS style override that applies to the marker's container.

Callbacks

`onClick`: (evt: [MapEvent](./types.md#mapevent)) => void {#onclick}

Called when the marker is clicked on.

`onDragStart`: (evt: [MarkerDragEvent](./types.md#markerdragevent)) => void {#ondragstart}

Called when dragging starts, if draggable is true.

`onDrag`: (evt: [MarkerDragEvent](./types.md#markerdragevent)) => void {#ondrag}

Called while dragging, if draggable is true.

`onDragEnd`: (evt: [MarkerDragEvent](./types.md#markerdragevent)) => void {#ondragend}

Called when dragging ends, if draggable is true.

Other Properties

The properties in this section are not reactive. They are only used when the component first mounts.

Any options supported by the Marker class, such as

anchor
color
scale
clickTolerance

Methods

The underlying native Marker instance is accessible via a React ref hook.
You may use it to call any imperative methods:

tsx

import * as React from 'react';
import {useRef, useMemo, useCallback} from 'react';
import {Map, Marker} from 'react-map-gl/maplibre';
import * as maplibregl from 'maplibre-gl';

function App() {
  const markerRef = useRef<maplibregl.Marker>();

  const popup = useMemo(() => {
    return maplibregl.Popup().setText('Hello world!');
  }, [])

  const togglePopup = useCallback(() => {
    markerRef.current?.togglePopup();
  }, []);

  return <>
    <Map>
      <Marker longitude={-122.4} latitude={37.8} color="red" popup={popup} ref={markerRef} />
    </Map>
    Toggle popup
  </>;
}

Source

marker.ts

NavigationControl

React component that wraps maplibre-gl's NavigationControl class.

tsx

import * as React from 'react';
import {Map, NavigationControl} from 'react-map-gl/maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

function App() {
  return <Map
    initialViewState={{
      longitude: -100,
      latitude: 40,
      zoom: 3.5
    }}
    mapStyle="https://demotiles.maplibre.org/style.json"
  >
    <NavigationControl />
  </Map>;
}

Properties

Reactive Properties

`style`: CSSProperties {#style}

CSS style override that applies to the control's container.

Other Properties

The properties in this section are not reactive. They are only used when the component first mounts.

Any options supported by the NavigationControl class, such as

showCompass
showZoom
visualizePitch

Plus the following:

`position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}

Default: 'top-right'

Placement of the control relative to the map.

Source

navigation-control.ts

File: README.md Copy Chapter

react-map-gl | [Docs](https://visgl.github.io/react-map-gl)

Installation Copy Section

Example Copy Section

Contribute Copy Section

Attributions Copy Section

File: docs/api-reference/maplibre/attribution-control.md Copy Chapter

AttributionControl

Properties Copy Chapter

Reactive Properties Copy Section

`style`: CSSProperties {#style}

Other Properties Copy Section

`position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}

Source Copy Chapter

File: docs/api-reference/maplibre/fullscreen-control.md Copy Chapter

FullscreenControl

Properties Copy Chapter

Reactive Properties Copy Section

`style`: CSSProperties {#style}

Other Properties Copy Section

`containerId`: string {#containerid}

`position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}

Source Copy Chapter

File: docs/api-reference/maplibre/geolocate-control.md Copy Chapter

GeolocateControl

Properties Copy Chapter

Reactive Properties Copy Section

`style`: CSSProperties {#style}

Callbacks Copy Section

`onGeolocate`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#ongeolocate}

`onError`: (evt: [GeolocateErrorEvent](./types.md#geolocateerrorevent)) => void {#onerror}

`onOutOfMaxBounds`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#onoutofmaxbounds}

`onTrackUserLocationStart`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationstart}

`onTrackUserLocationEnd`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationend}

Other Properties Copy Section

`position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}

Methods Copy Chapter

Source Copy Chapter

File: docs/api-reference/maplibre/layer.md Copy Chapter

Layer

Properties Copy Chapter

Identity Properties Copy Section

`id`: string {#id}

`type`: string {#type}

Options Copy Section

`beforeId`: string {#beforeid}

`source`: string {#source}

Source Copy Chapter

File: docs/api-reference/maplibre/logo-control.md Copy Chapter

LogoControl

Properties Copy Chapter

Reactive Properties Copy Section

`style`: CSSProperties {#style}

Other Properties Copy Section

`position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}

Source Copy Chapter

File: docs/api-reference/maplibre/map.md Copy Chapter

default (Map)

Properties Copy Chapter

Layout options Copy Section

`id`: string {#id}

`style`: CSSProperties {#style}

`cursor`: string {#cursor}

Styling options Copy Section

`light`: [Light](./types.md#light) {#light}

`mapStyle`: [MapStyle](./types.md#mapstyle) | string | Immutable {#mapstyle}

`projection`: string | [Projection](./types.md#projection) {#projection}

`renderWorldCopies`: boolean {#renderworldcopies}

`sky`: [Sky](./types.md#sky) {#sky}

`styleDiffing`: boolean {#stylediffing}

`terrain`: [Terrain](./types.md#terrain)|null {#terrain}

Camera options Copy Section

`initialViewState`: object {#initialviewstate}

`longitude`: number {#longitude}

`latitude`: number {#latitude}

`zoom`: number {#zoom}

`pitch`: number {#pitch}

`bearing`: number {#bearing}

`padding`: [PaddingOptions](./types.md#paddingoptions) {#padding}

`minZoom`: number {#minzoom}

File: README.md

Installation

Example

Contribute

Attributions

File: docs/api-reference/maplibre/attribution-control.md

Properties

Reactive Properties

Other Properties

Source

File: docs/api-reference/maplibre/fullscreen-control.md

Properties

Reactive Properties

Other Properties

Source

File: docs/api-reference/maplibre/geolocate-control.md

Properties

Reactive Properties

Callbacks

Other Properties

Methods

Source

File: docs/api-reference/maplibre/layer.md

Properties

Identity Properties

Options

Source

File: docs/api-reference/maplibre/logo-control.md

Properties

Reactive Properties

Other Properties

Source

File: docs/api-reference/maplibre/map.md

Properties

Layout options

Styling options

Camera options

Input handler options

Callbacks

Other options

Methods

Source

File: docs/api-reference/maplibre/map-provider.md