0
# Legacy Mapbox Components
1

2
Legacy implementation for backward compatibility with older Mapbox GL versions and existing applications. Provides the same component interfaces as the modern implementation but with legacy internal behavior and API patterns.
3

4
## Capabilities
5

6
### Legacy Map Component
7

8
Backward-compatible map component maintaining compatibility with older Mapbox GL JS versions and legacy application patterns.
9

10
```typescript { .api }
11
/**
12
 * Legacy map component providing backward compatibility
13
 * Maintains same interface as modern Map but with legacy behavior
14
 */
15
interface MapProps extends MapInitOptions, MapboxProps, GlobalSettings {
16
  /** Map library instance or promise - defaults to legacy mapbox-gl import */
17
  mapLib?: MapLib | Promise<MapLib>;
18
  /** Whether to reuse map instances */
19
  reuseMaps?: boolean;
20
  /** Map container DOM id */
21
  id?: string;
22
  /** Container CSS styles */
23
  style?: CSSProperties;
24
  /** Child components */
25
  children?: React.ReactNode;
26
}
27

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

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

36
### Legacy UI Components
37

38
Legacy implementations of markers, popups, and controls with backward-compatible behavior.
39

40
```typescript { .api }
41
/**
42
 * Legacy marker component with backward-compatible behavior
43
 */
44
interface MarkerProps {
45
  longitude: number;
46
  latitude: number;
47
  anchor?: string;
48
  offset?: PointLike;
49
  color?: string;
50
  scale?: number;
51
  draggable?: boolean;
52
  rotation?: number;
53
  rotationAlignment?: string;
54
  pitchAlignment?: string;
55
  clickTolerance?: number;
56
  onClick?: (event: MarkerEvent) => void;
57
  onDragStart?: (event: MarkerDragEvent) => void;
58
  onDrag?: (event: MarkerDragEvent) => void;
59
  onDragEnd?: (event: MarkerDragEvent) => void;
60
  style?: CSSProperties;
61
  className?: string;
62
  children?: React.ReactNode;
63
}
64

65
function Marker(props: MarkerProps): JSX.Element;
66

67
/**
68
 * Legacy popup component with backward-compatible behavior
69
 */
70
interface PopupProps {
71
  longitude: number;
72
  latitude: number;
73
  anchor?: string;
74
  offset?: PointLike;
75
  maxWidth?: string;
76
  className?: string;
77
  style?: CSSProperties;
78
  closeButton?: boolean;
79
  closeOnClick?: boolean;
80
  closeOnMove?: boolean;
81
  focusAfterOpen?: boolean;
82
  onClose?: () => void;
83
  onOpen?: () => void;
84
  children?: React.ReactNode;
85
}
86

87
function Popup(props: PopupProps): JSX.Element;
88
```
89

90
### Legacy Controls
91

92
Legacy implementations of map controls maintaining backward compatibility.
93

94
```typescript { .api }
95
/**
96
 * Legacy navigation control
97
 */
98
interface NavigationControlProps {
99
  position?: ControlPosition;
100
  showCompass?: boolean;
101
  showZoom?: boolean;
102
  visualizePitch?: boolean;
103
}
104

105
function NavigationControl(props: NavigationControlProps): JSX.Element;
106

107
/**
108
 * Legacy geolocation control
109
 */
110
interface GeolocateControlProps {
111
  position?: ControlPosition;
112
  positionOptions?: PositionOptions;
113
  fitBoundsOptions?: any;
114
  trackUserLocation?: boolean;
115
  showAccuracyCircle?: boolean;
116
  showUserLocation?: boolean;
117
  onGeolocate?: (event: GeolocateResultEvent) => void;
118
  onError?: (event: GeolocateErrorEvent) => void;
119
  onTrackUserLocationStart?: (event: GeolocateEvent) => void;
120
  onTrackUserLocationEnd?: (event: GeolocateEvent) => void;
121
}
122

123
function GeolocateControl(props: GeolocateControlProps): JSX.Element;
124

125
/**
126
 * Legacy fullscreen control
127
 */
128
interface FullscreenControlProps {
129
  position?: ControlPosition;
130
  container?: HTMLElement;
131
}
132

133
function FullscreenControl(props: FullscreenControlProps): JSX.Element;
134

135
/**
136
 * Legacy scale control
137
 */
138
interface ScaleControlProps {
139
  position?: ControlPosition;
140
  maxWidth?: number;
141
  unit?: 'imperial' | 'metric' | 'nautical';
142
}
143

144
function ScaleControl(props: ScaleControlProps): JSX.Element;
145

146
/**
147
 * Legacy attribution control
148
 */
149
interface AttributionControlProps {
150
  position?: ControlPosition;
151
  compact?: boolean;
152
  customAttribution?: string | string[];
153
}
154

155
function AttributionControl(props: AttributionControlProps): JSX.Element;
156
```
157

158
### Legacy Data Components
159

160
Legacy implementations of source and layer components.
161

162
```typescript { .api }
163
/**
164
 * Legacy source component with backward-compatible behavior
165
 * Extends SourceSpecification from MapBox with React-specific props
166
 */
167
interface SourceProps extends SourceSpecification, CanvasSourceSpecification {
168
  /** Optional source ID, auto-generated if not provided */
169
  id?: string;
170
  /** Child Layer components that use this source */
171
  children?: React.ReactNode;
172
}
173

174
function Source(props: SourceProps): JSX.Element;
175

176
/**
177
 * Legacy layer component with backward-compatible behavior
178
 * Extends LayerSpecification from MapBox with React-specific props
179
 */
180
interface LayerProps extends LayerSpecification, CustomLayerInterface {
181
  /** Optional layer ID, auto-generated if not provided */
182
  id?: string;
183
  /** Optional source ID, inherited from parent Source if not provided */
184
  source?: string;
185
  /** Insert layer before this layer ID for z-ordering */
186
  beforeId?: string;
187
}
188

189
function Layer(props: LayerProps): JSX.Element;
190
```
191

192
### Legacy Hooks and Context
193

194
Legacy hooks and context providers with backward-compatible behavior.
195

196
```typescript { .api }
197
/**
198
 * Legacy hook for accessing map instance
199
 */
200
function useMap(): MapRef;
201

202
/**
203
 * Legacy hook for custom control management
204
 */
205
function useControl<T extends IControl>(
206
  onCreate: (map: MapInstance) => T,
207
  onRemove?: (control: T) => void,
208
  options?: {position?: ControlPosition}
209
): T;
210

211
/**
212
 * Legacy context provider for map management
213
 */
214
interface MapProviderProps {
215
  children: React.ReactNode;
216
}
217

218
function MapProvider(props: MapProviderProps): JSX.Element;
219
```
220

221
### Legacy Utilities
222

223
Utility functions used internally by the legacy implementation.
224

225
```typescript { .api }
226
/**
227
 * Assertion utility for development-time checks
228
 */
229
function assert(condition: any, message?: string): asserts condition;
230

231
/**
232
 * Deep equality comparison utility
233
 */
234
function deepEqual(a: any, b: any): boolean;
235

236
/**
237
 * Isomorphic layout effect hook for SSR compatibility
238
 */
239
function useIsomorphicLayoutEffect(
240
  effect: React.EffectCallback,
241
  deps?: React.DependencyList
242
): void;
243

244
/**
245
 * Set global configuration for the legacy implementation
246
 */
247
function setGlobals(globals: GlobalSettings): void;
248

249
/**
250
 * Transform utilities for coordinate and style transformations
251
 */
252
interface TransformUtils {
253
  transformRequest?: (url: string, resourceType: string) => any;
254
  normalizeStyle?: (style: any) => any;
255
}
256

257
/**
258
 * Apply React-compatible styles to DOM elements
259
 */
260
function applyReactStyle(element: HTMLElement, style: CSSProperties): void;
261
```
262

263
## Usage Examples
264

265
**Basic Legacy Map Setup:**
266
```typescript
267
import React from 'react';
268
import Map, { Marker, NavigationControl } from 'react-map-gl/mapbox-legacy';
269
import 'mapbox-gl/dist/mapbox-gl.css';
270

271
function LegacyMap() {
272
  const [viewport, setViewport] = React.useState({
273
    longitude: -100,
274
    latitude: 40,
275
    zoom: 4,
276
    bearing: 0,
277
    pitch: 0
278
  });
279

280
  return (
281
    <Map
282
      {...viewport}
283
      width="100%"
284
      height="400px"
285
      mapStyle="mapbox://styles/mapbox/streets-v11"
286
      mapboxApiAccessToken="YOUR_TOKEN"
287
      onViewportChange={setViewport}
288
    >
289
      <Marker longitude={-100} latitude={40} />
290
      <NavigationControl style={{position: 'absolute', top: 0, right: 0}} />
291
    </Map>
292
  );
293
}
294
```
295

296
**Legacy Data Visualization:**
297
```typescript
298
import React from 'react';
299
import Map, { Source, Layer } from 'react-map-gl/mapbox-legacy';
300

301
function LegacyDataMap() {
302
  const [viewport, setViewport] = React.useState({
303
    longitude: -100,
304
    latitude: 40,
305
    zoom: 4
306
  });
307

308
  const data = {
309
    type: 'FeatureCollection',
310
    features: [
311
      // ... GeoJSON features
312
    ]
313
  };
314

315
  return (
316
    <Map
317
      {...viewport}
318
      width="100%"
319
      height="400px"
320
      mapStyle="mapbox://styles/mapbox/light-v10"
321
      mapboxApiAccessToken="YOUR_TOKEN"
322
      onViewportChange={setViewport}
323
    >
324
      <Source id="legacy-data" type="geojson" data={data}>
325
        <Layer
326
          id="legacy-layer"
327
          type="circle"
328
          paint={{
329
            'circle-radius': 6,
330
            'circle-color': '#007cbf'
331
          }}
332
        />
333
      </Source>
334
    </Map>
335
  );
336
}
337
```
338

339
## Migration Notes
340

341
When migrating from legacy to modern react-map-gl:
342

343
**Viewport Management:**
344
```typescript
345
// Legacy approach
346
const [viewport, setViewport] = useState({...});
347
<Map {...viewport} onViewportChange={setViewport} />
348

349
// Modern approach  
350
const [viewState, setViewState] = useState({...});
351
<Map {...viewState} onMove={evt => setViewState(evt.viewState)} />
352
```
353

354
**Size Properties:**
355
```typescript
356
// Legacy approach
357
<Map width="100%" height="400px" />
358

359
// Modern approach
360
<Map style={{width: '100%', height: 400}} />
361
```
362

363
**Token Property:**
364
```typescript
365
// Legacy approach
366
<Map mapboxApiAccessToken="TOKEN" />
367

368
// Modern approach
369
<Map mapboxAccessToken="TOKEN" />
370
```
371

372
## Key Differences
373

374
The legacy implementation differs from the modern version in several ways:
375

376
1. **Viewport vs ViewState**: Uses `viewport` and `onViewportChange` instead of `viewState` and `onMove`
377
2. **Size Properties**: Uses `width` and `height` props instead of `style` object
378
3. **Token Naming**: Uses `mapboxApiAccessToken` instead of `mapboxAccessToken`
379
4. **Event Handling**: Different event object structures and callback naming
380
5. **Internal Architecture**: Uses older patterns for component lifecycle and state management
381
6. **Performance**: Less optimized rendering and update patterns compared to modern implementation
382

383
## Legacy Types
384

385
```typescript { .api }
386
interface LegacyViewport {
387
  width: number | string;
388
  height: number | string;
389
  longitude: number;
390
  latitude: number;
391
  zoom: number;
392
  bearing?: number;
393
  pitch?: number;
394
  altitude?: number;
395
}
396

397
interface LegacyMapProps extends LegacyViewport {
398
  mapStyle?: string | any;
399
  mapboxApiAccessToken?: string;
400
  onViewportChange?: (viewport: LegacyViewport) => void;
401
  onClick?: (event: any) => void;
402
  onHover?: (event: any) => void;
403
  children?: React.ReactNode;
404
}
405

406
interface GlobalSettings {
407
  accessToken?: string;
408
  transformRequest?: (url: string, resourceType: string) => any;
409
}
410
```