0
# Core Map Components
1

2
Essential React components for rendering Google Maps, markers, and info windows. These components form the foundation of most Google Maps React applications.
3

4
## Capabilities
5

6
### GoogleMap
7

8
The main map component that renders a Google Map instance with full React integration.
9

10
```javascript { .api }
11
/**
12
 * Main Google Map component
13
 */
14
class GoogleMap extends Component<GoogleMapProps> {
15
  /** Adjusts the map bounds to fit the specified bounds */
16
  fitBounds(bounds: google.maps.LatLngBounds | google.maps.LatLngBoundsLiteral): void;
17
  /** Pans the map by the given distance in pixels */
18
  panBy(x: number, y: number): void;
19
  /** Pans the map to the specified coordinates */
20
  panTo(latLng: google.maps.LatLng | google.maps.LatLngLiteral): void;
21
  /** Pans the map to fit the specified bounds */
22
  panToBounds(latLngBounds: google.maps.LatLngBounds | google.maps.LatLngBoundsLiteral): void;
23
  /** Returns the current map bounds */
24
  getBounds(): google.maps.LatLngBounds;
25
  /** Returns the current map center */
26
  getCenter(): google.maps.LatLng;
27
  /** Returns whether icons are clickable */
28
  getClickableIcons(): boolean;
29
  /** Returns the map's DOM element */
30
  getDiv(): Element;
31
  /** Returns the current heading */
32
  getHeading(): number;
33
  /** Returns the current map type ID */
34
  getMapTypeId(): google.maps.MapTypeId | string;
35
  /** Returns the current projection */
36
  getProjection(): google.maps.Projection;
37
  /** Returns the Street View panorama */
38
  getStreetView(): google.maps.StreetViewPanorama;
39
  /** Returns the current tilt */
40
  getTilt(): number;
41
  /** Returns the current zoom level */
42
  getZoom(): number;
43
}
44

45
interface GoogleMapProps {
46
  // Default props (initial values)
47
  defaultCenter?: google.maps.LatLng | google.maps.LatLngLiteral;
48
  defaultClickableIcons?: boolean;
49
  defaultHeading?: number;
50
  defaultMapTypeId?: google.maps.MapTypeId | string;
51
  defaultOptions?: google.maps.MapOptions;
52
  defaultStreetView?: google.maps.StreetViewPanorama;
53
  defaultTilt?: number;
54
  defaultZoom?: number;
55
  
56
  // Controlled props (for controlled components)
57
  center?: google.maps.LatLng | google.maps.LatLngLiteral;
58
  clickableIcons?: boolean;
59
  heading?: number;
60
  mapTypeId?: google.maps.MapTypeId | string;
61
  options?: google.maps.MapOptions;
62
  streetView?: google.maps.StreetViewPanorama;
63
  tilt?: number;
64
  zoom?: number;
65
  
66
  // Event handlers
67
  onBoundsChanged?(): void;
68
  onCenterChanged?(): void;
69
  onClick?(e: google.maps.MouseEvent | google.maps.IconMouseEvent): void;
70
  onDblClick?(e: google.maps.MouseEvent): void;
71
  onDrag?(): void;
72
  onDragEnd?(): void;
73
  onDragStart?(): void;
74
  onHeadingChanged?(): void;
75
  onIdle?(): void;
76
  onMapTypeIdChanged?(): void;
77
  onMouseMove?(e: google.maps.MouseEvent): void;
78
  onMouseOut?(e: google.maps.MouseEvent): void;
79
  onMouseOver?(e: google.maps.MouseEvent): void;
80
  onProjectionChanged?(): void;
81
  onResize?(): void;
82
  onRightClick?(e: google.maps.MouseEvent): void;
83
  onTilesLoaded?(): void;
84
  onTiltChanged?(): void;
85
  onZoomChanged?(): void;
86
}
87
```
88

89
**Usage Example:**
90

91
```javascript
92
import { GoogleMap, withGoogleMap, withScriptjs } from "react-google-maps";
93

94
const Map = withScriptjs(withGoogleMap(() => (
95
  <GoogleMap
96
    defaultZoom={10}
97
    defaultCenter={{ lat: 37.7749, lng: -122.4194 }}
98
    defaultOptions={{
99
      streetViewControl: false,
100
      scaleControl: true,
101
      mapTypeControl: true,
102
      panControl: false,
103
      zoomControl: true,
104
      rotateControl: false,
105
      fullscreenControl: true
106
    }}
107
    onClick={(event) => {
108
      console.log("Map clicked at:", event.latLng.lat(), event.latLng.lng());
109
    }}
110
    onZoomChanged={() => {
111
      console.log("Map zoom changed");
112
    }}
113
  >
114
    {/* Child components like Marker, InfoWindow, etc. */}
115
  </GoogleMap>
116
)));
117
```
118

119
### Marker
120

121
Component for displaying markers on the map with support for animations, custom icons, and interactivity.
122

123
```javascript { .api }
124
/**
125
 * Map marker component
126
 */
127
class Marker extends Component<MarkerProps> {
128
  /** Returns the marker's animation */
129
  getAnimation(): google.maps.Animation;
130
  /** Returns whether the marker is clickable */
131
  getClickable(): boolean;
132
  /** Returns the marker's cursor */
133
  getCursor(): string;
134
  /** Returns whether the marker is draggable */
135
  getDraggable(): boolean;
136
  /** Returns the marker's icon */
137
  getIcon(): string | google.maps.Icon | google.maps.Symbol;
138
  /** Returns the marker's label */
139
  getLabel(): google.maps.MarkerLabel;
140
  /** Returns the marker's opacity */
141
  getOpacity(): number;
142
  /** Returns the marker's place */
143
  getPlace(): google.maps.Place;
144
  /** Returns the marker's position */
145
  getPosition(): google.maps.LatLng;
146
  /** Returns the marker's shape */
147
  getShape(): google.maps.MarkerShape;
148
  /** Returns the marker's title */
149
  getTitle(): string;
150
  /** Returns whether the marker is visible */
151
  getVisible(): boolean;
152
  /** Returns the marker's z-index */
153
  getZIndex(): number;
154
}
155

156
interface MarkerProps {
157
  // Default props
158
  defaultAnimation?: google.maps.Animation;
159
  defaultClickable?: boolean;
160
  defaultCursor?: string;
161
  defaultDraggable?: boolean;
162
  defaultIcon?: string | google.maps.Icon | google.maps.Symbol;
163
  defaultLabel?: google.maps.MarkerLabel;
164
  defaultOpacity?: number;
165
  defaultOptions?: google.maps.MarkerOptions;
166
  defaultPlace?: google.maps.Place;
167
  defaultPosition?: google.maps.LatLng | google.maps.LatLngLiteral;
168
  defaultShape?: google.maps.MarkerShape;
169
  defaultTitle?: string;
170
  defaultVisible?: boolean;
171
  defaultZIndex?: number;
172
  
173
  // Controlled props
174
  animation?: google.maps.Animation;
175
  attribution?: google.maps.Attribution;
176
  clickable?: boolean;
177
  cursor?: string;
178
  draggable?: boolean;
179
  icon?: string | google.maps.Icon | google.maps.Symbol;
180
  label?: google.maps.MarkerLabel;
181
  opacity?: number;
182
  options?: google.maps.MarkerOptions;
183
  place?: google.maps.Place;
184
  position?: google.maps.LatLng | google.maps.LatLngLiteral;
185
  shape?: google.maps.MarkerShape;
186
  title?: string;
187
  visible?: boolean;
188
  zIndex?: number;
189
  
190
  // Event handlers
191
  onAnimationChanged?(): void;
192
  onClick?(e: google.maps.MouseEvent): void;
193
  onClickableChanged?(): void;
194
  onCursorChanged?(): void;
195
  onDblClick?(e: google.maps.MouseEvent): void;
196
  onDrag?(e: google.maps.MouseEvent): void;
197
  onDraggableChanged?(): void;
198
  onDragEnd?(e: google.maps.MouseEvent): void;
199
  onDragStart?(e: google.maps.MouseEvent): void;
200
  onFlatChanged?(): void;
201
  onIconChanged?(): void;
202
  onMouseDown?(e: google.maps.MouseEvent): void;
203
  onMouseOut?(e: google.maps.MouseEvent): void;
204
  onMouseOver?(e: google.maps.MouseEvent): void;
205
  onMouseUp?(e: google.maps.MouseEvent): void;
206
  onPositionChanged?(): void;
207
  onRightClick?(e: google.maps.MouseEvent): void;
208
  onShapeChanged?(): void;
209
  onTitleChanged?(): void;
210
  onVisibleChanged?(): void;
211
  onZindexChanged?(): void;
212
}
213
```
214

215
**Usage Example:**
216

217
```javascript
218
import { Marker } from "react-google-maps";
219

220
<GoogleMap defaultZoom={10} defaultCenter={{ lat: 37.7749, lng: -122.4194 }}>
221
  <Marker
222
    position={{ lat: 37.7749, lng: -122.4194 }}
223
    title="San Francisco"
224
    icon={{
225
      url: "https://maps.google.com/mapfiles/ms/icons/red-dot.png",
226
      scaledSize: { width: 32, height: 32 }
227
    }}
228
    animation={google.maps.Animation.DROP}
229
    draggable={true}
230
    onClick={() => {
231
      console.log("Marker clicked!");
232
    }}
233
    onDragEnd={(event) => {
234
      console.log("Marker moved to:", event.latLng.lat(), event.latLng.lng());
235
    }}
236
  />
237
</GoogleMap>
238
```
239

240
### InfoWindow
241

242
Component for displaying information windows on the map, typically shown when markers are clicked.
243

244
```javascript { .api }
245
/**
246
 * Info window component for displaying content in a popup
247
 */
248
class InfoWindow extends Component<InfoWindowProps> {
249
  /** Returns the info window's position */
250
  getPosition(): google.maps.LatLng;
251
  /** Returns the info window's z-index */
252
  getZIndex(): number;
253
}
254

255
interface InfoWindowProps {
256
  // Default props
257
  defaultOptions?: google.maps.InfoWindowOptions;
258
  defaultPosition?: google.maps.LatLng | google.maps.LatLngLiteral;
259
  defaultZIndex?: number;
260
  
261
  // Controlled props
262
  options?: google.maps.InfoWindowOptions;
263
  position?: google.maps.LatLng | google.maps.LatLngLiteral;
264
  zIndex?: number;
265
  
266
  // Event handlers
267
  onCloseClick?(): void;
268
  onDomReady?(): void;
269
  onContentChanged?(): void;
270
  onPositionChanged?(): void;
271
  onZindexChanged?(): void;
272
}
273
```
274

275
**Usage Example:**
276

277
```javascript
278
import { InfoWindow } from "react-google-maps";
279

280
const [showInfoWindow, setShowInfoWindow] = useState(false);
281

282
<GoogleMap defaultZoom={10} defaultCenter={{ lat: 37.7749, lng: -122.4194 }}>
283
  <Marker
284
    position={{ lat: 37.7749, lng: -122.4194 }}
285
    onClick={() => setShowInfoWindow(true)}
286
  />
287
  
288
  {showInfoWindow && (
289
    <InfoWindow
290
      position={{ lat: 37.7749, lng: -122.4194 }}
291
      onCloseClick={() => setShowInfoWindow(false)}
292
    >
293
      <div>
294
        <h3>San Francisco</h3>
295
        <p>The City by the Bay</p>
296
        <img src="/sf-image.jpg" alt="San Francisco" style={{ width: "200px" }} />
297
      </div>
298
    </InfoWindow>
299
  )}
300
</GoogleMap>
301
```
302

303
## Common Patterns
304

305
### Controlled vs Uncontrolled Components
306

307
Most components support both controlled and uncontrolled patterns:
308

309
```javascript
310
// Uncontrolled (using default props)
311
<GoogleMap 
312
  defaultZoom={10} 
313
  defaultCenter={{ lat: 37.7749, lng: -122.4194 }} 
314
/>
315

316
// Controlled (using state)
317
const [zoom, setZoom] = useState(10);
318
const [center, setCenter] = useState({ lat: 37.7749, lng: -122.4194 });
319

320
<GoogleMap 
321
  zoom={zoom} 
322
  center={center}
323
  onZoomChanged={() => setZoom(map.getZoom())}
324
  onCenterChanged={() => setCenter(map.getCenter().toJSON())}
325
/>
326
```
327

328
### Event Handling
329

330
All components follow React conventions for event handling:
331

332
```javascript
333
<Marker
334
  position={{ lat: 37.7749, lng: -122.4194 }}
335
  onClick={(event) => {
336
    // event is a google.maps.MouseEvent
337
    console.log("Clicked at:", event.latLng.lat(), event.latLng.lng());
338
  }}
339
  onDragEnd={(event) => {
340
    // Handle marker drag
341
    updateMarkerPosition(event.latLng.toJSON());
342
  }}
343
/>
344
```