0
# React Map GL
1

2
React Map GL provides React components for MapLibre GL JS and Mapbox GL JS, offering a React-friendly API wrapper for interactive mapping applications. The library enables developers to integrate performant, customizable maps into React applications with declarative components, hooks, and comprehensive TypeScript support.
3

4
## Package Information
5

6
- **Package Name**: react-map-gl
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-map-gl`
10

11
## Core Imports
12

13
React Map GL provides three different import paths for different mapping backends:
14

15
**For Mapbox GL JS:**
16
```typescript
17
import Map, { 
18
  Marker, 
19
  Popup, 
20
  NavigationControl, 
21
  Source, 
22
  Layer, 
23
  useMap, 
24
  MapProvider 
25
} from "react-map-gl/mapbox";
26
```
27

28
**For MapLibre GL JS:**
29
```typescript
30
import Map, { 
31
  Marker, 
32
  Popup, 
33
  NavigationControl, 
34
  Source, 
35
  Layer, 
36
  useMap, 
37
  MapProvider,
38
  TerrainControl,
39
  LogoControl 
40
} from "react-map-gl/maplibre";
41
```
42

43
**For Legacy Mapbox (backwards compatibility):**
44
```typescript
45
import Map, { 
46
  Marker, 
47
  Popup, 
48
  NavigationControl, 
49
  Source, 
50
  Layer, 
51
  useMap, 
52
  MapProvider 
53
} from "react-map-gl/mapbox-legacy";
54
```
55

56
CommonJS:
57
```javascript
58
const { 
59
  Map, 
60
  Marker, 
61
  Popup, 
62
  NavigationControl, 
63
  Source, 
64
  Layer, 
65
  useMap, 
66
  MapProvider 
67
} = require("react-map-gl/mapbox");
68
```
69

70
## Basic Usage
71

72
```typescript
73
import React from 'react';
74
import Map, { Marker, Popup, NavigationControl } from 'react-map-gl/mapbox';
75
import 'mapbox-gl/dist/mapbox-gl.css';
76

77
function MyMap() {
78
  const [viewState, setViewState] = React.useState({
79
    longitude: -100,
80
    latitude: 40,
81
    zoom: 3.5,
82
    bearing: 0,
83
    pitch: 0,
84
    padding: { top: 0, bottom: 0, left: 0, right: 0 }
85
  });
86

87
  return (
88
    <Map
89
      {...viewState}
90
      onMove={evt => setViewState(evt.viewState)}
91
      style={{width: 600, height: 400}}
92
      mapStyle="mapbox://styles/mapbox/streets-v9"
93
      mapboxAccessToken="YOUR_MAPBOX_TOKEN"
94
    >
95
      <Marker longitude={-100} latitude={40} color="red" />
96
      <NavigationControl position="top-right" />
97
    </Map>
98
  );
99
}
100
```
101

102
## Architecture
103

104
React Map GL is built around several key architectural patterns:
105

106
- **Multiple Backend Support**: Three export paths supporting Mapbox GL, MapLibre GL, and legacy Mapbox implementations
107
- **Declarative Components**: Map, markers, popups, controls, sources, and layers as React components
108
- **Hooks Integration**: Custom hooks for map access, control management, and state handling
109
- **Type Safety**: Full TypeScript definitions with generic type preservation
110
- **Event System**: Comprehensive event handling for map interactions, view changes, and user interactions
111
- **Ref Pattern**: Imperative map access through React refs for advanced use cases
112

113
## Capabilities
114

115
### Core Map Component
116

117
The main Map component providing the foundation for interactive mapping applications. Supports both controlled and uncontrolled patterns with comprehensive event handling.
118

119
```typescript { .api }
120
interface MapProps extends MapInitOptions, MapboxProps, GlobalSettings {
121
  mapLib?: MapLib | Promise<MapLib>;
122
  reuseMaps?: boolean;
123
  id?: string;
124
  style?: CSSProperties;
125
  children?: any;
126
}
127

128
interface MapRef {
129
  getMap(): MapInstance;
130
}
131

132
function Map(props: MapProps): JSX.Element;
133
```
134

135
### UI Components
136

137
Interactive map elements including markers, popups, and map controls for building rich mapping experiences.
138

139
```typescript { .api }
140
interface MarkerProps {
141
  longitude: number;
142
  latitude: number;
143
  anchor?: string;
144
  offset?: PointLike;
145
  color?: string;
146
  scale?: number;
147
  draggable?: boolean;
148
  rotation?: number;
149
  rotationAlignment?: string;
150
  pitchAlignment?: string;
151
  onClick?: (event: MarkerEvent) => void;
152
  onDragStart?: (event: MarkerDragEvent) => void;
153
  onDrag?: (event: MarkerDragEvent) => void;
154
  onDragEnd?: (event: MarkerDragEvent) => void;
155
  style?: CSSProperties;
156
  className?: string;
157
  children?: any;
158
}
159

160
function Marker(props: MarkerProps): JSX.Element;
161

162
interface PopupProps {
163
  longitude: number;
164
  latitude: number;
165
  anchor?: string;
166
  offset?: PointLike;
167
  maxWidth?: string;
168
  className?: string;
169
  style?: CSSProperties;
170
  closeButton?: boolean;
171
  closeOnClick?: boolean;
172
  closeOnMove?: boolean;
173
  focusAfterOpen?: boolean;
174
  onClose?: () => void;
175
  children?: any;
176
}
177

178
function Popup(props: PopupProps): JSX.Element;
179
```
180

181
[Mapbox and MapLibre Components](./mapbox-maplibre.md)
182

183
### Data Sources and Layers
184

185
Components for managing map data sources and rendering layers, enabling custom data visualization and styling.
186

187
```typescript { .api }
188
interface SourceProps extends SourceSpecification {
189
  id?: string;
190
  children?: React.ReactNode;
191
}
192

193
function Source(props: SourceProps): JSX.Element;
194

195
interface LayerProps extends LayerSpecification {
196
  id?: string;
197
  beforeId?: string;
198
}
199

200
function Layer(props: LayerProps): JSX.Element;
201
```
202

203
### Map Controls
204

205
Interactive controls for map navigation, geolocation, attribution, and other map functions.
206

207
```typescript { .api }
208
interface NavigationControlProps {
209
  position?: ControlPosition;
210
  showCompass?: boolean;
211
  showZoom?: boolean;
212
  visualizePitch?: boolean;
213
}
214

215
function NavigationControl(props: NavigationControlProps): JSX.Element;
216

217
interface GeolocateControlProps {
218
  position?: ControlPosition;
219
  positionOptions?: PositionOptions;
220
  fitBoundsOptions?: FitBoundsOptions;
221
  trackUserLocation?: boolean;
222
  showAccuracyCircle?: boolean;
223
  showUserLocation?: boolean;
224
}
225

226
function GeolocateControl(props: GeolocateControlProps): JSX.Element;
227

228
interface AttributionControlProps {
229
  position?: ControlPosition;
230
  compact?: boolean;
231
  customAttribution?: string | string[];
232
}
233

234
function AttributionControl(props: AttributionControlProps): JSX.Element;
235

236
interface FullscreenControlProps {
237
  position?: ControlPosition;
238
  container?: HTMLElement;
239
}
240

241
function FullscreenControl(props: FullscreenControlProps): JSX.Element;
242

243
interface ScaleControlProps {
244
  position?: ControlPosition;
245
  maxWidth?: number;
246
  unit?: 'imperial' | 'metric' | 'nautical';
247
}
248

249
function ScaleControl(props: ScaleControlProps): JSX.Element;
250
```
251

252
### Hooks and Context
253

254
React hooks and context providers for accessing map instances and creating custom controls.
255

256
```typescript { .api }
257
function useMap(): MapRef;
258

259
function useControl<T extends IControl>(
260
  onCreate: (map: MapInstance) => T,
261
  onRemove?: (control: T) => void,
262
  options?: { position?: ControlPosition }
263
): T;
264

265
interface MapProviderProps {
266
  children: React.ReactNode;
267
}
268

269
function MapProvider(props: MapProviderProps): JSX.Element;
270
```
271

272
### Legacy Implementation
273

274
Backward-compatible implementation for applications using older Mapbox GL versions and patterns.
275

276
```typescript { .api }
277
// Same component interfaces as modern implementation
278
// but with legacy internal behavior and compatibility
279
```
280

281
[Legacy Mapbox Components](./mapbox-legacy.md)
282

283
### Event System and Types
284

285
Comprehensive event handling system with strongly-typed event objects for all map interactions.
286

287
```typescript { .api }
288
interface ViewState {
289
  longitude: number;
290
  latitude: number;
291
  zoom: number;
292
  bearing: number;
293
  pitch: number;
294
  padding: PaddingOptions;
295
}
296

297
interface ViewStateChangeEvent {
298
  viewState: ViewState;
299
  interactionState: InteractionState;
300
  originalEvent: Event;
301
}
302

303
interface InteractionState {
304
  inTransition: boolean;
305
  isDragging: boolean;
306
  isPanning: boolean;
307
  isRotating: boolean;
308
  isZooming: boolean;
309
}
310

311
interface MapCallbacks {
312
  onMove?: (event: ViewStateChangeEvent) => void;
313
  onMoveStart?: (event: ViewStateChangeEvent) => void;
314
  onMoveEnd?: (event: ViewStateChangeEvent) => void;
315
  onClick?: (event: MapMouseEvent) => void;
316
  onDblClick?: (event: MapMouseEvent) => void;
317
  onMouseDown?: (event: MapMouseEvent) => void;
318
  onMouseUp?: (event: MapMouseEvent) => void;
319
  onMouseOver?: (event: MapMouseEvent) => void;
320
  onMouseMove?: (event: MapMouseEvent) => void;
321
  onMouseOut?: (event: MapMouseEvent) => void;
322
  onContextMenu?: (event: MapMouseEvent) => void;
323
  onWheel?: (event: MapWheelEvent) => void;
324
  onTouchStart?: (event: MapTouchEvent) => void;
325
  onTouchEnd?: (event: MapTouchEvent) => void;
326
  onTouchMove?: (event: MapTouchEvent) => void;
327
  onTouchCancel?: (event: MapTouchEvent) => void;
328
}
329
```
330

331
[Events and Types](./events-types.md)
332

333
## Key Types
334

335
```typescript { .api }
336
// Geometric types
337
type Point = {
338
  x: number;
339
  y: number;
340
};
341

342
type PointLike = Point | [number, number];
343

344
type LngLat = {
345
  lng: number;
346
  lat: number;
347
};
348

349
type LngLatLike = LngLat | [number, number] | {lon: number; lat: number};
350

351
type LngLatBounds = {
352
  _sw: LngLat;
353
  _ne: LngLat;
354
};
355

356
type LngLatBoundsLike = 
357
  | LngLatBounds 
358
  | [LngLatLike, LngLatLike] 
359
  | [number, number, number, number];
360

361
type PaddingOptions = {
362
  top?: number;
363
  bottom?: number;
364
  left?: number;
365
  right?: number;
366
};
367

368
// Control positioning
369
type ControlPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
370

371
// Source types
372
interface SourceSpecification {
373
  type: 'vector' | 'raster' | 'raster-dem' | 'geojson' | 'image' | 'video' | 'canvas';
374
  url?: string;
375
  tiles?: string[];
376
  bounds?: [number, number, number, number];
377
  scheme?: 'xyz' | 'tms';
378
  minzoom?: number;
379
  maxzoom?: number;
380
  attribution?: string;
381
  data?: any;
382
  coordinates?: [[number, number], [number, number], [number, number], [number, number]];
383
  canvas?: string | HTMLCanvasElement;
384
}
385

386
// Layer types
387
interface LayerSpecification {
388
  id: string;
389
  type: 'fill' | 'line' | 'symbol' | 'circle' | 'heatmap' | 'fill-extrusion' | 'raster' | 'hillshade' | 'background' | 'sky' | 'custom';
390
  source?: string;
391
  'source-layer'?: string;
392
  minzoom?: number;
393
  maxzoom?: number;
394
  filter?: any[];
395
  layout?: Record<string, any>;
396
  paint?: Record<string, any>;
397
}
398

399
// Map instance types
400
interface MapLib {
401
  Map: any;
402
  Marker: any;
403
  Popup: any;
404
  AttributionControl: any;
405
  FullscreenControl: any;
406
  GeolocateControl: any;
407
  NavigationControl: any;
408
  ScaleControl: any;
409
}
410

411
interface MapInstance extends MapLib.Map {
412
  // Extended with library-specific methods
413
}
414

415
// Control interface
416
interface IControl {
417
  onAdd(map: MapInstance): HTMLElement;
418
  onRemove(map: MapInstance): void;
419
}
420

421
// Geolocation types
422
interface PositionOptions {
423
  enableHighAccuracy?: boolean;
424
  timeout?: number;
425
  maximumAge?: number;
426
}
427

428
interface FitBoundsOptions {
429
  padding?: number | PaddingOptions;
430
  linear?: boolean;
431
  easing?: (t: number) => number;
432
  around?: LngLatLike;
433
  maxZoom?: number;
434
  duration?: number;
435
}
436

437
// Context and hooks
438
interface MountedMapsContext {
439
  onMapMount: (map: MapRef, mapId: string) => void;
440
  onMapUnmount: (mapId: string) => void;
441
  maps: Record<string, MapRef>;
442
}
443
```