0
# Script Loading & Initialization
1

2
Script loading utilities for initializing the Google Maps JavaScript API with various configuration options, loading strategies, and error handling mechanisms.
3

4
## Capabilities
5

6
### LoadScript Component
7

8
Class-based component that loads the Google Maps JavaScript API via script injection with comprehensive configuration options.
9

10
```typescript { .api }
11
/**
12
 * Loads Google Maps JavaScript API with script injection
13
 * Class-based component with lifecycle management
14
 */
15
interface LoadScriptProps extends LoadScriptUrlOptions {
16
  children?: React.ReactNode;
17
  id: string;
18
  nonce?: string;
19
  loadingElement?: React.ReactNode;
20
  onLoad?: () => void;
21
  onError?: (error: Error) => void;
22
  onUnmount?: () => void;
23
  preventGoogleFontsLoading?: boolean;
24
}
25

26
interface LoadScriptUrlOptions {
27
  googleMapsApiKey: string;
28
  libraries?: Libraries;
29
  language?: string;
30
  region?: string;
31
  version?: string;
32
  channel?: string;
33
  mapIds?: string[];
34
}
35

36
function LoadScript(props: LoadScriptProps): JSX.Element;
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import React from 'react';
43
import { LoadScript, GoogleMap } from '@react-google-maps/api';
44

45
// Basic usage
46
function App() {
47
  return (
48
    <LoadScript
49
      id="script-loader"
50
      googleMapsApiKey="YOUR_API_KEY"
51
      libraries={['places', 'drawing']}
52
    >
53
      <GoogleMap
54
        center={{ lat: 40.7128, lng: -74.0060 }}
55
        zoom={10}
56
        mapContainerStyle={{ width: '100%', height: '400px' }}
57
      />
58
    </LoadScript>
59
  );
60
}
61

62
// With loading state and error handling
63
function AppWithLoading() {
64
  return (
65
    <LoadScript
66
      id="script-loader"
67
      googleMapsApiKey="YOUR_API_KEY"
68
      libraries={['places', 'drawing', 'geometry']}
69
      language="en"
70
      region="US"
71
      version="weekly"
72
      loadingElement={<div>Loading Maps...</div>}
73
      onLoad={() => console.log('Maps API loaded')}
74
      onError={(error) => console.error('Failed to load Maps API', error)}
75
    >
76
      <GoogleMap
77
        center={{ lat: 40.7128, lng: -74.0060 }}
78
        zoom={10}
79
        mapContainerStyle={{ width: '100%', height: '400px' }}
80
      />
81
    </LoadScript>
82
  );
83
}
84
```
85

86
### LoadScriptNext Component
87

88
Hook-based alternative to LoadScript that uses useLoadScript internally, providing a more modern React approach.
89

90
```typescript { .api }
91
/**
92
 * Hook-based alternative to LoadScript using useLoadScript internally
93
 * Provides modern React hooks approach to script loading
94
 */
95
interface LoadScriptNextProps extends UseLoadScriptOptions {
96
  loadingElement?: React.ReactElement;
97
  onLoad?: () => void;
98
  onError?: (error: Error) => void;
99
  onUnmount?: () => void;
100
  children: React.ReactElement;
101
}
102

103
function LoadScriptNext(props: LoadScriptNextProps): JSX.Element;
104
```
105

106
**Usage Examples:**
107

108
```typescript
109
import React from 'react';
110
import { LoadScriptNext, GoogleMap } from '@react-google-maps/api';
111

112
function ModernApp() {
113
  return (
114
    <LoadScriptNext
115
      googleMapsApiKey="YOUR_API_KEY"
116
      libraries={['places', 'drawing']}
117
      loadingElement={<div>Loading...</div>}
118
    >
119
      <GoogleMap
120
        center={{ lat: 40.7128, lng: -74.0060 }}
121
        zoom={10}
122
        mapContainerStyle={{ width: '100%', height: '400px' }}
123
      />
124
    </LoadScriptNext>
125
  );
126
}
127
```
128

129
### useLoadScript Hook
130

131
React hook for loading the Google Maps API script with built-in loading state management and error handling.
132

133
```typescript { .api }
134
/**
135
 * Hook for loading Google Maps API script with state management
136
 * @param options - Configuration options for loading the script
137
 * @returns Object with loading state, error, and script URL
138
 */
139
interface UseLoadScriptOptions extends LoadScriptUrlOptions {
140
  id?: string;
141
  nonce?: string;
142
  preventGoogleFontsLoading?: boolean;
143
}
144

145
function useLoadScript(options: UseLoadScriptOptions): {
146
  isLoaded: boolean;
147
  loadError: Error | undefined;
148
  url: string;
149
};
150
```
151

152
**Usage Examples:**
153

154
```typescript
155
import React from 'react';
156
import { useLoadScript, GoogleMap } from '@react-google-maps/api';
157

158
function HookBasedApp() {
159
  const { isLoaded, loadError } = useLoadScript({
160
    googleMapsApiKey: "YOUR_API_KEY",
161
    libraries: ['places', 'drawing'],
162
    language: 'en',
163
    region: 'US'
164
  });
165

166
  if (loadError) {
167
    return <div>Error loading maps</div>;
168
  }
169

170
  if (!isLoaded) {
171
    return <div>Loading maps</div>;
172
  }
173

174
  return (
175
    <GoogleMap
176
      center={{ lat: 40.7128, lng: -74.0060 }}
177
      zoom={10}
178
      mapContainerStyle={{ width: '100%', height: '400px' }}
179
    />
180
  );
181
}
182

183
// Advanced usage with conditional loading
184
function ConditionalMap() {
185
  const [shouldLoadMap, setShouldLoadMap] = React.useState(false);
186
  
187
  const { isLoaded, loadError } = useLoadScript({
188
    googleMapsApiKey: shouldLoadMap ? "YOUR_API_KEY" : "",
189
    libraries: ['places'],
190
    preventGoogleFontsLoading: true
191
  });
192

193
  return (
194
    <div>
195
      <button onClick={() => setShouldLoadMap(true)}>
196
        Load Map
197
      </button>
198
      
199
      {shouldLoadMap && isLoaded && (
200
        <GoogleMap
201
          center={{ lat: 40.7128, lng: -74.0060 }}
202
          zoom={10}
203
          mapContainerStyle={{ width: '100%', height: '400px' }}
204
        />
205
      )}
206
    </div>
207
  );
208
}
209
```
210

211
### useJsApiLoader Hook
212

213
Alternative hook that uses @googlemaps/js-api-loader internally, providing a different approach to script loading.
214

215
```typescript { .api }
216
/**
217
 * Alternative hook using @googlemaps/js-api-loader
218
 * Provides different loading strategy compared to useLoadScript
219
 * @param options - Configuration options for the JS API loader
220
 * @returns Object with loading state and error information
221
 */
222
function useJsApiLoader(options: UseLoadScriptOptions): {
223
  isLoaded: boolean;
224
  loadError: Error | undefined;
225
};
226
```
227

228
**Usage Examples:**
229

230
```typescript
231
import React from 'react';
232
import { useJsApiLoader, GoogleMap } from '@react-google-maps/api';
233

234
function JsApiLoaderApp() {
235
  const { isLoaded, loadError } = useJsApiLoader({
236
    googleMapsApiKey: "YOUR_API_KEY",
237
    libraries: ['places', 'geometry'],
238
    version: "weekly"
239
  });
240

241
  if (loadError) {
242
    return <div>Error loading Google Maps API</div>;
243
  }
244

245
  if (!isLoaded) {
246
    return <div>Loading Google Maps API...</div>;
247
  }
248

249
  return (
250
    <GoogleMap
251
      center={{ lat: 40.7128, lng: -74.0060 }}
252
      zoom={10}
253
      mapContainerStyle={{ width: '100%', height: '400px' }}
254
    />
255
  );
256
}
257
```
258

259
### Libraries Configuration
260

261
Type definition and configuration for Google Maps API libraries that can be loaded.
262

263
```typescript { .api }
264
/**
265
 * Available Google Maps API libraries that can be loaded
266
 * Each library provides specific functionality and must be loaded before use
267
 */
268
type Libraries = Library[];
269

270
// Available library options (complete list):
271
type Library = 
272
  | 'drawing'        // Drawing Manager, overlays, and drawing tools
273
  | 'geometry'       // Geometry utilities (spherical, poly, encoding)
274
  | 'localContext'   // Local Context API for place details
275
  | 'places'         // Places API (autocomplete, search, details)
276
  | 'visualization'  // Data visualization (heatmaps, clustering)
277
  | string;          // Custom libraries
278

279
// Common library combinations:
280
const commonLibraries: Libraries = [
281
  'places',      // Places API for autocomplete, search
282
  'drawing',     // Drawing tools and shapes
283
  'geometry',    // Geometric utility functions
284
  'visualization' // Heatmap and other visualizations
285
];
286

287
const basicLibraries: Libraries = ['places'];
288
const advancedLibraries: Libraries = ['places', 'drawing', 'geometry'];
289
const fullLibraries: Libraries = ['places', 'drawing', 'geometry', 'visualization', 'localContext'];
290
```
291

292
**Library Usage Examples:**
293

294
```typescript
295
// Load specific libraries for different features
296
const placesLibraries: Libraries = ['places'];
297
const drawingLibraries: Libraries = ['drawing', 'geometry'];
298
const visualizationLibraries: Libraries = ['visualization'];
299
const allLibraries: Libraries = ['places', 'drawing', 'geometry', 'visualization', 'localContext'];
300

301
// Use with LoadScript
302
<LoadScript
303
  googleMapsApiKey="YOUR_API_KEY"
304
  libraries={allLibraries}
305
>
306
  {/* Your map components */}
307
</LoadScript>
308

309
// Use with hooks
310
const { isLoaded } = useLoadScript({
311
  googleMapsApiKey: "YOUR_API_KEY",
312
  libraries: placesLibraries
313
});
314
```
315

316
### Advanced Configuration
317

318
Advanced configuration options for script loading behavior and optimization.
319

320
```typescript { .api }
321
/**
322
 * Advanced configuration options for script loading
323
 */
324
interface LoadScriptUrlOptions {
325
  googleMapsApiKey: string;
326
  libraries?: Libraries;
327
  language?: string;        // Language code (e.g., 'en', 'es', 'fr')
328
  region?: string;         // Region code (e.g., 'US', 'GB', 'DE')
329
  version?: string;        // API version ('weekly', 'quarterly', or specific version)
330
  channel?: string;        // Release channel for Google Maps Platform
331
  mapIds?: string[];       // Map IDs for custom styling
332
}
333
```
334

335
**Advanced Usage Examples:**
336

337
```typescript
338
// Localized map with region-specific defaults
339
const { isLoaded } = useLoadScript({
340
  googleMapsApiKey: "YOUR_API_KEY",
341
  libraries: ['places'],
342
  language: 'es',
343
  region: 'ES',
344
  version: 'weekly'
345
});
346

347
// Enterprise configuration with custom map styles
348
const { isLoaded } = useLoadScript({
349
  googleMapsApiKey: "YOUR_API_KEY",
350
  libraries: ['places', 'drawing'],
351
  channel: 'enterprise',
352
  mapIds: ['your-custom-map-style-id'],
353
  version: 'quarterly'
354
});
355

356
// Security-focused configuration
357
<LoadScript
358
  id="secure-script-loader"
359
  googleMapsApiKey="YOUR_API_KEY"
360
  nonce="your-csp-nonce"
361
  preventGoogleFontsLoading={true}
362
  libraries={['places']}
363
>
364
  <GoogleMap />
365
</LoadScript>
366
```