react-map-gl: a React wrapper for MapLibre GL and Mapbox GL

What react-map-gl wraps, and who ends up using it

The package is a set of React components that expose mapbox-gl or maplibre-gl through a React API. That is the whole scope. It does not ship tiles, a style editor, or a geocoder. If your problem is "I have a MapLibre or Mapbox map and I want it to live inside a component tree instead of an imperative init call", this is the layer for it. If your problem is "I need a map and I have no tile source", react-map-gl does not solve that part.

The audience is React application developers who already have a reason to use one of the two GL engines. The README's own example loads a style from `https://api.maptiler.com/maps/streets/style.json?key=<Maptiler access token>`, which tells you the intended shape: the component is the shell, and a third-party style URL fills it. Teams that need WebGL vector rendering, pitch and bearing, or custom layers are the ones who end up here rather than on a static image map.

The repository is part of vis.gl, described in the README as an OpenJS Foundation project. Development is also supported by Mapbox, per the attributions section. That is worth reading carefully: the wrapper is vendor-neutral in its API surface, but one of the two engines is backed by a company whose logo appears in the README's attribution block.

Two entry points, one component tree

The mechanism that matters is the import path. The README shows `import Map from 'react-map-gl/maplibre'` and `import Map from 'react-map-gl/mapbox'` as separate examples, each paired with its own CSS import: `maplibre-gl/dist/maplibre-gl.css` or `mapbox-gl/dist/mapbox-gl.css`. The engine itself is a peer dependency you install alongside the wrapper, not something react-map-gl bundles.

That design has a direct consequence. Swapping engines is not a config change, it is a code change: the import path, the CSS file, and the way you authenticate all move together. MapLibre takes a style URL that may carry its own key, as in the MapTiler example. Mapbox takes `mapboxAccessToken` as a prop, with the README pointing at a dedicated docs page for tokens. If you are writing a component library that must support both, you are writing two adapters.

The view state is the other half of the API. The examples pass `initialViewState` with `longitude`, `latitude`, and `zoom`, and set `style={{width: 600, height: 400}}` on the component. The map is sized by the container, so a zero-height parent gives you a zero-height map. Nothing in the README suggests react-map-gl infers size from anything else.

Installing react-map-gl and rendering a first map

Installation is two packages, and the README notes that using react-map-gl requires `react >= 16.3`. Pick the engine first, because the install command differs.

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

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

With the packages in place, the MapLibre path is the one that does not require a Mapbox account. The README's example imports the component, imports the stylesheet, and renders with an initial view over San Francisco. The `mapStyle` value is a MapTiler style URL with a placeholder key, so you need your own token from that provider before the basemap will draw.

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

The Mapbox variant is the same component with three differences: the import path, the CSS file, and a `mapboxAccessToken` prop instead of a key inside the style URL.

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

function App() {
  return (
    <Map
      mapboxAccessToken="<Mapbox access token>"
      initialViewState={{
        longitude: -100,
        latitude: 40,
        zoom: 3.5
      }}
      style={{width: 600, height: 400}}
      mapStyle="mapbox://styles/mapbox/streets-v9"
    />
  );
}

What you should see after either block is a 600 by 400 map at the coordinates you passed. If the panel is blank, check the CSS import first, then the token. A missing stylesheet is the most common cause of a map that renders nothing visible.

The token is the failure mode, not the component

react-map-gl cannot fail on its own for most production incidents, because it does not serve the data. The failure modes live one layer down. A Mapbox token that is missing, expired, or scoped to the wrong account produces a map that initializes and then draws nothing useful. The README links to a tokens page rather than explaining token scopes inline, so the wrapper's documentation will not tell you why your requests are being rejected.

The same applies to MapLibre with a hosted style. The README's example URL is a third-party style endpoint with a key in the query string. That key is visible in client-side code by construction, since the whole component runs in the browser. If your style provider bills per request, your billing is now a function of how many users load the page, and the wrapper offers no built-in caching or request budget.

There is also a version surface the README does not cover. The repository's dev dependencies pin `mapbox-gl-v1` at 1.13.0 and `mapbox-gl-v3` at 3.9.0, which indicates the project tests against more than one major version of the Mapbox engine. That is a signal about the project's own test matrix, not a promise about which version you should install. Your engine version is your choice and your compatibility risk.

react-map-gl versus using maplibre-gl directly

The honest alternative is not another React map library. It is skipping the wrapper and calling `new maplibregl.Map({...})` inside a `useEffect`, then wiring your own refs, cleanup, and event listeners. That approach gives you the full engine API with no translation layer, and it removes a dependency from your bundle.

The difference is ownership of lifecycle. Direct maplibre-gl means you write the effect that creates the map, the cleanup that removes it, and the code that reconciles React state changes into imperative map calls. react-map-gl exists to own that reconciliation. If your map is one component with a fixed style and no dynamic layers, the wrapper is a convenience you may not need. If you have dozens of components reacting to the same view state, the wrapper is doing real work.

A second comparison worth naming is the engine choice itself, since the README treats MapLibre and Mapbox as interchangeable at the component level. They are not interchangeable at the account level. MapLibre is the open path; Mapbox brings the token and the billing relationship. The wrapper makes the code look similar, which can hide how different the operational commitments are.

Maintenance, releases, and what the licence file actually says

The repository is not archived, and the last push was on 2026-09-03. Releases have been frequent: v8.1.1 on 2026-04-11, v8.1.2 on 2026-07-29, and v8.1.3 on 2026-09-02. That cadence is visible in the release list and in the CHANGELOG.md at the repository root, which is where you should look before upgrading a minor version.

The licence situation needs a caveat. The repository metadata reports NOASSERTION, while the monorepo `package.json` declares `"license": "MIT"`. Those two statements do not match, and the README does not reconcile them. Read the LICENSE file at the root before you rely on either. This is a factual discrepancy, not a legal opinion, and it is the kind of thing a compliance review will flag.

Upgrade cost is mostly engine-shaped. Because maplibre-gl and mapbox-gl are peer dependencies, a major bump in either engine lands on you, not on react-map-gl. The project's own test matrix runs against mapbox-gl 1.13.0 and 3.9.0, so a jump across those majors is at least a path the maintainers exercise. There is no documented rollback procedure in the README; the CHANGELOG and the release tags are what you have to work with.

Editorial conclusion

Adopt react-map-gl if you want the map engine to stay a peer dependency and you are willing to keep the style URL, the access token, and the CSS import aligned with whichever entry point you pick. Do not adopt it expecting a tile server, a geocoder, or a free basemap: the package renders the map, the data and the billing come from maplibre-gl, mapbox-gl, or a style provider such as MapTiler. Before you commit, check that your React version satisfies react >= 16.3, confirm the import path matches the engine you installed, and read the Mapbox token page the README links to so you know which account the requests will be charged to.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. visgl/react-map-gl on GitHub