Table of Contents

Adding Custom Data

Native Mapbox Layers

You can inject data and mapbox native layers by modifying the map style object:

import {fromJS} from 'immutable';
const mapStyle = fromJS({
    version: 8,
    sources: {
        points: {
            type: 'geojson',
            data: {
                type: 'FeatureCollection',
                features: [
                    {type: 'Feature', geometry: {type: 'Point', coordinates: [-122.45, 37.78]}}
    layers: [
            id: 'my-layer',
            type: 'circle',
            source: 'points',
            paint: {
                'circle-color': '#f00',
                'circle-radius': 4

<ReactMapGL mapStyle={mapStyle} ... />

For details about data sources and layer configuration, check out the Mapbox style specification.

For dynamically updating data and layers, check out the GeoJSON and GeoJSON animation examples.


react-map-gl provides a basic overlay API that enables applications to overlay data on top of maps.

Note that the built-in overlays are intended to provide basic functionality only. For more feature rich and performant data visualization overlay use cases, consider using


import {SVGOverlay} from 'react-map-gl';

function redraw({project}) {
  const [cx, cy] = project([-122, 37]);
  return <circle cx={cx} cy={cy} r={4} fill="blue" />;

<MapGL {...viewport}>
  <SVGOverlay redraw={redraw} />

Built-in Overlays

Built-in overlays are: SVGOverlay, HTMLOverlay, and CanvasOverlay. They are imported using

import {SVGOverlay, HTMLOverlay, CanvasOverlay} from 'react-map-gl';

Example Overlays

There are a couple of additional overlays in the examples folder that can be copied into applications ScatterplotOverlay, DraggablePointsOverlay, ChoroplethOverlay.

Third-party Overlays

Third party overlays can also be created. For example, the heatmap-overlay uses webgl-heatmap to create geographic heatmaps.

import HeatmapOverlay from 'react-map-gl-heatmap-overlay';
import cities from 'example-cities';

<MapGL {...viewport}>
  <HeatmapOverlay locations={cities} {...viewport} />

Want to create and share your own overlay? Check the examples/additional-overlays folder for examples.