0
# Mapbox and MapLibre Components
1

2
Core mapping components for building interactive map applications with either Mapbox GL JS or MapLibre GL JS backends. These components provide identical APIs with backend-specific optimizations.
3

4
## Capabilities
5

6
### Map Component
7

8
The foundational map component that renders the interactive map and serves as a container for all other map elements.
9

10
```typescript { .api }
11
/**
12
 * Main map component providing interactive mapping functionality
13
 * Supports both controlled and uncontrolled patterns with comprehensive event handling
14
 */
15
interface MapProps extends MapInitOptions, MapboxProps, GlobalSettings {
16
  /** Map library instance or promise resolving to map library */
17
  mapLib?: MapLib | Promise<MapLib>;
18
  /** Whether to reuse map instances for performance optimization */
19
  reuseMaps?: boolean;
20
  /** Map container DOM id */
21
  id?: string;
22
  /** Container CSS styles */
23
  style?: CSSProperties;
24
  /** Child components (markers, popups, controls, etc.) */
25
  children?: React.ReactNode;
26
}
27

28
interface MapRef {
29
  /** Get the underlying map instance for imperative operations */
30
  getMap(): MapInstance;
31
}
32

33
function Map(props: MapProps): JSX.Element;
34
```
35

36
**Key Map Props:**
37
```typescript { .api }
38
interface MapInitOptions {
39
  /** Initial longitude */
40
  longitude?: number;
41
  /** Initial latitude */
42
  latitude?: number;
43
  /** Initial zoom level */
44
  zoom?: number;
45
  /** Initial bearing in degrees */
46
  bearing?: number;
47
  /** Initial pitch in degrees */
48
  pitch?: number;
49
  /** Map style URL or object */
50
  mapStyle?: string | any;
51
  /** Mapbox access token (Mapbox only) */
52
  mapboxAccessToken?: string;
53
}
54

55
interface MapboxProps extends MapCallbacks {
56
  /** Current view state for controlled component */
57
  viewState?: ViewState;
58
  /** Initial view state for uncontrolled component */
59
  initialViewState?: ViewState;
60
  
61
  /** Interactive behavior settings */
62
  interactive?: boolean;
63
  scrollZoom?: boolean | ScrollZoomOptions;
64
  boxZoom?: boolean;
65
  dragRotate?: boolean;
66
  dragPan?: boolean | DragPanOptions;
67
  keyboard?: boolean;
68
  doubleClickZoom?: boolean;
69
  touchZoomRotate?: boolean | TouchZoomRotateOptions;
70
  touchPitch?: boolean | TouchPitchOptions;
71
  
72
  /** Constraints */
73
  minZoom?: number;
74
  maxZoom?: number;
75
  minPitch?: number;
76
  maxPitch?: number;
77
  maxBounds?: LngLatBoundsLike;
78
  
79
  /** Styling */
80
  cursor?: string;
81
  
82
  /** Animation */
83
  transitionDuration?: number;
84
  transitionInterpolator?: any;
85
  
86
  /** Callbacks */
87
  onLoad?: () => void;
88
  onError?: (error: ErrorEvent) => void;
89
  onResize?: () => void;
90
  onRemove?: () => void;
91
  onData?: (event: MapStyleDataEvent | MapSourceDataEvent) => void;
92
  onStyleData?: (event: MapStyleDataEvent) => void;
93
  onSourceData?: (event: MapSourceDataEvent) => void;
94
}
95
```
96

97
### Marker Component
98

99
Displays markers at specific geographic coordinates with customizable appearance and behavior.
100

101
```typescript { .api }
102
/**
103
 * Map marker component for displaying points of interest
104
 * Supports dragging, custom styling, and event handling
105
 */
106
interface MarkerProps {
107
  /** Marker longitude */
108
  longitude: number;
109
  /** Marker latitude */
110
  latitude: number;
111
  
112
  /** Visual positioning */
113
  anchor?: 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
114
  offset?: PointLike;
115
  
116
  /** Appearance */
117
  color?: string;
118
  scale?: number;
119
  rotation?: number;
120
  rotationAlignment?: 'map' | 'viewport' | 'auto';
121
  pitchAlignment?: 'map' | 'viewport' | 'auto';
122
  
123
  /** Behavior */
124
  draggable?: boolean;
125
  clickTolerance?: number;
126
  
127
  /** Events */
128
  onClick?: (event: MarkerEvent) => void;
129
  onDragStart?: (event: MarkerDragEvent) => void;
130
  onDrag?: (event: MarkerDragEvent) => void;
131
  onDragEnd?: (event: MarkerDragEvent) => void;
132
  
133
  /** Styling */
134
  style?: CSSProperties;
135
  className?: string;
136
  children?: React.ReactNode;
137
}
138

139
function Marker(props: MarkerProps): JSX.Element;
140
```
141

142
### Popup Component
143

144
Displays information popups attached to specific geographic coordinates or markers.
145

146
```typescript { .api }
147
/**
148
 * Map popup component for displaying contextual information
149
 * Can be anchored to coordinates or follow markers
150
 */
151
interface PopupProps {
152
  /** Popup longitude */
153
  longitude: number;
154
  /** Popup latitude */
155
  latitude: number;
156
  
157
  /** Positioning */
158
  anchor?: 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
159
  offset?: PointLike;
160
  
161
  /** Appearance */
162
  maxWidth?: string;
163
  className?: string;
164
  style?: CSSProperties;
165
  
166
  /** Behavior */
167
  closeButton?: boolean;
168
  closeOnClick?: boolean;
169
  closeOnMove?: boolean;
170
  focusAfterOpen?: boolean;
171
  
172
  /** Events */
173
  onClose?: () => void;
174
  onOpen?: () => void;
175
  
176
  /** Content */
177
  children?: React.ReactNode;
178
}
179

180
function Popup(props: PopupProps): JSX.Element;
181
```
182

183
### Map Controls
184

185
Built-in control components for common map interactions and UI elements.
186

187
```typescript { .api }
188
/**
189
 * Navigation control with zoom and compass functionality
190
 */
191
interface NavigationControlProps {
192
  position?: ControlPosition;
193
  showCompass?: boolean;
194
  showZoom?: boolean;
195
  visualizePitch?: boolean;
196
}
197

198
function NavigationControl(props: NavigationControlProps): JSX.Element;
199

200
/**
201
 * Geolocation control for user location tracking
202
 */
203
interface GeolocateControlProps {
204
  position?: ControlPosition;
205
  positionOptions?: PositionOptions;
206
  fitBoundsOptions?: any;
207
  trackUserLocation?: boolean;
208
  showAccuracyCircle?: boolean;
209
  showUserLocation?: boolean;
210
  onGeolocate?: (event: GeolocateResultEvent) => void;
211
  onError?: (event: GeolocateErrorEvent) => void;
212
  onTrackUserLocationStart?: (event: GeolocateEvent) => void;
213
  onTrackUserLocationEnd?: (event: GeolocateEvent) => void;
214
}
215

216
function GeolocateControl(props: GeolocateControlProps): JSX.Element;
217

218
/**
219
 * Fullscreen toggle control
220
 */
221
interface FullscreenControlProps {
222
  position?: ControlPosition;
223
  container?: HTMLElement;
224
}
225

226
function FullscreenControl(props: FullscreenControlProps): JSX.Element;
227

228
/**
229
 * Scale indicator control
230
 */
231
interface ScaleControlProps {
232
  position?: ControlPosition;
233
  maxWidth?: number;
234
  unit?: 'imperial' | 'metric' | 'nautical';
235
}
236

237
function ScaleControl(props: ScaleControlProps): JSX.Element;
238

239
/**
240
 * Attribution control for map data credits
241
 */
242
interface AttributionControlProps {
243
  position?: ControlPosition;
244
  compact?: boolean;
245
  customAttribution?: string | string[];
246
}
247

248
function AttributionControl(props: AttributionControlProps): JSX.Element;
249
```
250

251
### MapLibre-Specific Controls
252

253
Additional controls available only when using MapLibre GL JS backend.
254

255
```typescript { .api }
256
/**
257
 * Terrain control for 3D terrain visualization (MapLibre only)
258
 */
259
interface TerrainControlProps {
260
  position?: ControlPosition;
261
  source?: string;
262
  exaggeration?: number;
263
}
264

265
function TerrainControl(props: TerrainControlProps): JSX.Element;
266

267
/**
268
 * Logo control for displaying MapLibre logo (MapLibre only)
269
 */
270
interface LogoControlProps {
271
  position?: ControlPosition;
272
}
273

274
function LogoControl(props: LogoControlProps): JSX.Element;
275
```
276

277
### Data Sources and Layers
278

279
Components for adding and styling data on the map.
280

281
```typescript { .api }
282
/**
283
 * Data source component for providing data to map layers
284
 * Extends SourceSpecification from MapBox/MapLibre with React-specific props
285
 */
286
interface SourceProps extends SourceSpecification, CanvasSourceSpecification {
287
  /** Optional source ID, auto-generated if not provided */
288
  id?: string;
289
  /** Child Layer components that use this source */
290
  children?: React.ReactNode;
291
}
292

293
function Source(props: SourceProps): JSX.Element;
294

295
/**
296
 * Map layer component for styling and displaying source data
297
 * Extends LayerSpecification from MapBox/MapLibre with React-specific props
298
 */
299
interface LayerProps extends LayerSpecification, CustomLayerInterface {
300
  /** Optional layer ID, auto-generated if not provided */
301
  id?: string;
302
  /** Optional source ID, inherited from parent Source if not provided */
303
  source?: string;
304
  /** Insert layer before this layer ID for z-ordering */
305
  beforeId?: string;
306
}
307

308
function Layer(props: LayerProps): JSX.Element;
309
```
310

311
### Hooks and Context
312

313
React hooks and context providers for advanced map integration.
314

315
```typescript { .api }
316
/**
317
 * Hook for accessing the current map instance
318
 * Must be used within a Map component's children
319
 */
320
function useMap(): MapRef;
321

322
/**
323
 * Hook for creating and managing custom map controls
324
 * Handles control lifecycle and positioning
325
 */
326
function useControl<T extends IControl>(
327
  onCreate: (map: MapInstance) => T,
328
  onRemove?: (control: T) => void,
329
  options?: {position?: ControlPosition}
330
): T;
331

332
/**
333
 * Context provider for managing multiple map instances
334
 * Enables map sharing and coordination between components
335
 */
336
interface MapProviderProps {
337
  children: React.ReactNode;
338
}
339

340
function MapProvider(props: MapProviderProps): JSX.Element;
341
```
342

343
## Usage Examples
344

345
**Basic Map with Markers:**
346
```typescript
347
import React from 'react';
348
import Map, { Marker, Popup, NavigationControl } from 'react-map-gl/mapbox';
349

350
function InteractiveMap() {
351
  const [selectedMarker, setSelectedMarker] = React.useState(null);
352
  
353
  const markers = [
354
    {id: 1, longitude: -100, latitude: 40, title: "Marker 1"},
355
    {id: 2, longitude: -95, latitude: 35, title: "Marker 2"}
356
  ];
357

358
  return (
359
    <Map
360
      initialViewState={{
361
        longitude: -100,
362
        latitude: 40,
363
        zoom: 4
364
      }}
365
      style={{width: '100%', height: 400}}
366
      mapStyle="mapbox://styles/mapbox/streets-v12"
367
      mapboxAccessToken="YOUR_TOKEN"
368
    >
369
      {markers.map(marker => (
370
        <Marker
371
          key={marker.id}
372
          longitude={marker.longitude}
373
          latitude={marker.latitude}
374
          onClick={() => setSelectedMarker(marker)}
375
        />
376
      ))}
377
      
378
      {selectedMarker && (
379
        <Popup
380
          longitude={selectedMarker.longitude}
381
          latitude={selectedMarker.latitude}
382
          onClose={() => setSelectedMarker(null)}
383
        >
384
          <div>{selectedMarker.title}</div>
385
        </Popup>
386
      )}
387
      
388
      <NavigationControl position="top-right" />
389
    </Map>
390
  );
391
}
392
```
393

394
**Advanced Data Visualization:**
395
```typescript
396
import React from 'react';
397
import Map, { Source, Layer } from 'react-map-gl/maplibre';
398

399
function DataVisualization() {
400
  const geojsonData = {
401
    type: 'FeatureCollection',
402
    features: [
403
      // ... GeoJSON features
404
    ]
405
  };
406

407
  const layerStyle = {
408
    id: 'data-layer',
409
    type: 'fill',
410
    paint: {
411
      'fill-color': ['get', 'color'],
412
      'fill-opacity': 0.8
413
    }
414
  };
415

416
  return (
417
    <Map
418
      initialViewState={{longitude: -100, latitude: 40, zoom: 4}}
419
      style={{width: '100%', height: 400}}
420
      mapStyle="https://demotiles.maplibre.org/style.json"
421
    >
422
      <Source id="data-source" type="geojson" data={geojsonData}>
423
        <Layer {...layerStyle} />
424
      </Source>
425
    </Map>
426
  );
427
}
428
```
429

430
## Common Types
431

432
```typescript { .api }
433
type ControlPosition = 
434
  | 'top-left' 
435
  | 'top-right' 
436
  | 'bottom-left' 
437
  | 'bottom-right';
438

439
interface IControl {
440
  onAdd(map: MapInstance): HTMLElement;
441
  onRemove(map: MapInstance): void;
442
  getDefaultPosition?(): ControlPosition;
443
}
444

445
interface ScrollZoomOptions {
446
  around?: 'center';
447
}
448

449
interface DragPanOptions {
450
  linearity?: number;
451
  easing?: (t: number) => number;
452
  maxSpeed?: number;
453
  deceleration?: number;
454
}
455

456
interface TouchZoomRotateOptions {
457
  around?: 'center';
458
}
459

460
interface TouchPitchOptions {
461
  around?: 'center';
462
}
463

464
// Source and Layer types from MapBox/MapLibre
465
interface SourceSpecification {
466
  type: 'vector' | 'raster' | 'raster-dem' | 'geojson' | 'image' | 'video';
467
  url?: string;
468
  tiles?: string[];
469
  bounds?: [number, number, number, number];
470
  scheme?: 'xyz' | 'tms';
471
  minzoom?: number;
472
  maxzoom?: number;
473
  attribution?: string;
474
  // Additional properties vary by source type
475
}
476

477
interface CanvasSourceSpecification {
478
  type: 'canvas';
479
  coordinates: [[number, number], [number, number], [number, number], [number, number]];
480
  animate?: boolean;
481
  canvas: string | HTMLCanvasElement;
482
}
483

484
interface LayerSpecification {
485
  id: string;
486
  type: 'fill' | 'line' | 'symbol' | 'circle' | 'heatmap' | 'fill-extrusion' | 'raster' | 'hillshade' | 'background' | 'sky';
487
  source?: string;
488
  'source-layer'?: string;
489
  minzoom?: number;
490
  maxzoom?: number;
491
  filter?: any[];
492
  layout?: Record<string, any>;
493
  paint?: Record<string, any>;
494
}
495

496
interface CustomLayerInterface {
497
  id: string;
498
  type: 'custom';
499
  renderingMode?: '2d' | '3d';
500
  onAdd?(map: MapInstance, gl: WebGLRenderingContext): void;
501
  onRemove?(map: MapInstance, gl: WebGLRenderingContext): void;
502
  prerender?(gl: WebGLRenderingContext, matrix: number[]): void;
503
  render(gl: WebGLRenderingContext, matrix: number[]): void;
504
}
505
```