Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

react-map-gl

visgl2.7mMIT8.0.4TypeScript support: included

React components for MapLibre GL JS and Mapbox GL JS

mapbox, maplibre, mapbox-gl, maplibre-gl, react

readme

version build downloads

react-map-gl | Docs

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

or

# 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>"
    />
  );
}

or

// 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

changelog

CHANGELOG

Version 8.0

v8.0.4 (Apr 15, 2025)

  • Revert changes to add source condition (#2526)

v8.0.3 (Apr 9, 2025)

  • Fix addSource condition (#2524)

v8.0.2 (Mar 28, 2025)

  • Fix source loading condition (#2513)
  • Remove support() check (#2508)
  • marker.ts: undefined instead of null (#2500)
  • Fix: Handle className prop change (#2483)
  • Fix style loading check on Source layers (#2377) (#2493)

v8.0.1 (Feb 6, 2025)

  • Fix type resolution for subpath exports when using moduleResolution: node (#2486)

v8.0.0 (Feb 3, 2025)

  • First version to support Mapbox GL JS' official types and MapLibre GL JS v5. This version fully separates the code that support each compatible map library:
    • react-map-gl/mapbox: for use with mapbox-gl>=3.5.0
    • react-map-gl/maplibre: for use with maplibre-gl>=4
    • react-map-gl/mapbox-legacy: for use with mapbox-gl v1.x and v2.x and @types/mapbox-gl
  • As a result, each endpoint now have slightly smaller bundle size and more precise types.
  • Maplibre wrapper is expected to have better functionality and performance than v7 by utilizing an upstream API for the React use case.

For a full list of breaking changes, please visit the upgrade guide.

v8.0.0-beta.1 (Jan 31, 2025)

  • feat: remove RTLTextPlugin default for MapLibre (#2480)

v8.0.0-alpha.2 (Jan 27, 2025)

  • Migrate to monorepo (#2459)

Version 7.2

7.2.0-beta.1 (Sep 12, 2023)

  • Switch to ESM module (#2281)

Version 7.1

7.1.0-beta.3 (Jun 22, 2023)

  • Remap event types (#2207)
  • Restore fog, light and terrain types on MapProps (#2206)

7.1.0-beta.2 (Jun 14, 2023)

  • Make source prop of Layer optional (#2200)
  • Fix maplibre-gl peerDependencies typo (#2197)

7.1.0-beta.1 (Jun 5, 2023)

  • Add ref forwarding to Marker and Popup (#2191)
  • Split exports into separate endpoints (#2178)
  • Make mapbox-gl an optional dependency (#2175)
  • Remove defaultProps and displayName (#2173)

Version 7.0

7.0.0 (Feb 4, 2022)

v7 is a complete rewrite of the library. It addresses many long-standing issues in v5 and v6 limited by legacy architecture decisions. The most notable results of this redesign are:

  • Performance: minimize the overhead of React, offer the same fast and smooth interaction as the native library
  • Lightweight: the ESM build size is reduced from 219k to 57k
  • Predictability: Components behave the same as their mapbox counterparts. Props are mapped 1:1 from the native options wherever appropriate. Almost all imperative APIs (flyTo, fitBounds etc.) can now be called directly without breaking the React binding.
  • Compatibility: first and third-party plugins! Directly use mapbox-gl-draw, mapbox-gl-geocoder, to name a few.
  • TypeScript compliant: the code base is now entirely written in TypeScript, and all types can be imported.

Visit the upgrade guide if you are trying to upgrade from v5 and v6.

7.0.0-beta.1 (Jan 26, 2022)

  • Add mapLib API (#1703)
  • Support inline styling for all components (#1702)
  • Refactor Mapbox class (#1701)

7.0.0-alpha.7 (Jan 17, 2022)

  • Improve typing (#1695)
  • [v7] Fix popup className update in mapbox v1/maplibre (#1694)

7.0.0-alpha.6 (Jan 9, 2022)

  • [v7] Fix double controls in strict mode (#1678)
  • [v7] Fix AttributionControl prop typo (#1679)

7.0.0-alpha.5 (Jan 6, 2022)

  • [v7] Handle unmount order (#1676)
  • [v7] Fix synchronization during transition (#1675)
  • [v7] Update MapRef (#1674)
  • [v7] Bug fixes (#1673)

7.0.0-alpha.4 (Jan 4, 2022)

  • [v7] Fix resize synchronization (#1670)
  • [v7] Add fog, light, terrain props (#1669)
  • [v7] support global settings with MapProps (#1668)

7.0.0-alpha.3 (Jan 3, 2022)

  • [v7] Clean up typings and expose more utility types (#1667)
  • Drop flow types support (#1666)

7.0.0-alpha.2 (Jan 2, 2022)

  • Update @types/mapbox-gl dependency

7.0.0-alpha.1 (Jan 2, 2022)

  • [v7] utility hooks (#1663)
  • [v7] Add Layer and Source (#1657)
  • [v7] Control components (#1656)
  • [v7] Marker and Popup (#1655)
  • [v7] Map component (#1652)
  • Typescript dev setup