0
# Shape Overlays
1

2
Geometric shape components for drawing circles, polygons, polylines, and rectangles on Google Maps. These components support interactive editing, styling, and event handling.
3

4
## Capabilities
5

6
### Circle
7

8
Component for rendering circular overlays on the map with support for editing and customization.
9

10
```javascript { .api }
11
/**
12
 * Circular overlay component
13
 */
14
class Circle extends Component<CircleProps> {
15
  /** Returns the circle's bounds */
16
  getBounds(): google.maps.LatLngBounds;
17
  /** Returns the circle's center */
18
  getCenter(): google.maps.LatLng;
19
  /** Returns whether the circle is draggable */
20
  getDraggable(): boolean;
21
  /** Returns whether the circle is editable */
22
  getEditable(): boolean;
23
  /** Returns the circle's radius in meters */
24
  getRadius(): number;
25
  /** Returns whether the circle is visible */
26
  getVisible(): boolean;
27
}
28

29
interface CircleProps {
30
  // Default props
31
  defaultCenter?: google.maps.LatLng | google.maps.LatLngLiteral;
32
  defaultDraggable?: boolean;
33
  defaultEditable?: boolean;
34
  defaultOptions?: google.maps.CircleOptions;
35
  defaultRadius?: number;
36
  defaultVisible?: boolean;
37
  
38
  // Controlled props
39
  center?: google.maps.LatLng | google.maps.LatLngLiteral;
40
  draggable?: boolean;
41
  editable?: boolean;
42
  options?: google.maps.CircleOptions;
43
  radius?: number;
44
  visible?: boolean;
45
  
46
  // Event handlers
47
  onCenterChanged?(): void;
48
  onClick?(e: google.maps.MouseEvent): void;
49
  onDrag?(e: google.maps.MouseEvent): void;
50
  onDblClick?(e: google.maps.MouseEvent): void;
51
  onDragEnd?(e: google.maps.MouseEvent): void;
52
  onDragStart?(e: google.maps.MouseEvent): void;
53
  onMouseDown?(e: google.maps.MouseEvent): void;
54
  onMouseMove?(e: google.maps.MouseEvent): void;
55
  onMouseOut?(e: google.maps.MouseEvent): void;
56
  onMouseOver?(e: google.maps.MouseEvent): void;
57
  onMouseUp?(e: google.maps.MouseEvent): void;
58
  onRadiusChanged?(): void;
59
  onRightClick?(e: google.maps.MouseEvent): void;
60
}
61
```
62

63
**Usage Example:**
64

65
```javascript
66
import { Circle } from "react-google-maps";
67

68
<GoogleMap defaultZoom={10} defaultCenter={{ lat: 37.7749, lng: -122.4194 }}>
69
  <Circle
70
    center={{ lat: 37.7749, lng: -122.4194 }}
71
    radius={5000} // 5km radius
72
    options={{
73
      fillColor: "#ff0000",
74
      fillOpacity: 0.35,
75
      strokeColor: "#ff0000",
76
      strokeOpacity: 0.8,
77
      strokeWeight: 2,
78
    }}
79
    editable={true}
80
    draggable={true}
81
    onCenterChanged={() => {
82
      console.log("Circle center changed");
83
    }}
84
    onRadiusChanged={() => {
85
      console.log("Circle radius changed");
86
    }}
87
  />
88
</GoogleMap>
89
```
90

91
### Polygon
92

93
Component for rendering polygonal shapes with support for multiple paths and holes.
94

95
```javascript { .api }
96
/**
97
 * Polygonal overlay component
98
 */
99
class Polygon extends Component<PolygonProps> {
100
  /** Returns whether the polygon is draggable */
101
  getDraggable(): boolean;
102
  /** Returns whether the polygon is editable */
103
  getEditable(): boolean;
104
  /** Returns the polygon's path (outer boundary) */
105
  getPath(): google.maps.MVCArray<google.maps.LatLng>;
106
  /** Returns all paths (including holes) */
107
  getPaths(): google.maps.MVCArray<google.maps.MVCArray<google.maps.LatLng>>;
108
  /** Returns whether the polygon is visible */
109
  getVisible(): boolean;
110
}
111

112
interface PolygonProps {
113
  // Default props
114
  defaultDraggable?: boolean;
115
  defaultEditable?: boolean;
116
  defaultOptions?: google.maps.PolygonOptions;
117
  defaultPath?: google.maps.MVCArray<google.maps.LatLng> | Array<google.maps.LatLng | google.maps.LatLngLiteral>;
118
  defaultPaths?: google.maps.MVCArray<google.maps.MVCArray<google.maps.LatLng>> | google.maps.MVCArray<google.maps.LatLng> | Array<Array<google.maps.LatLng | google.maps.LatLngLiteral>> | Array<google.maps.LatLng | google.maps.LatLngLiteral>;
119
  defaultVisible?: boolean;
120
  
121
  // Controlled props
122
  draggable?: boolean;
123
  editable?: boolean;
124
  options?: google.maps.PolygonOptions;
125
  path?: google.maps.MVCArray<google.maps.LatLng> | Array<google.maps.LatLng | google.maps.LatLngLiteral>;
126
  paths?: google.maps.MVCArray<google.maps.MVCArray<google.maps.LatLng>> | google.maps.MVCArray<google.maps.LatLng> | Array<Array<google.maps.LatLng | google.maps.LatLngLiteral>> | Array<google.maps.LatLng | google.maps.LatLngLiteral>;
127
  visible?: boolean;
128
  
129
  // Event handlers
130
  onClick?(e: google.maps.PolyMouseEvent): void;
131
  onDblClick?(e: google.maps.PolyMouseEvent): void;
132
  onDrag?(e: google.maps.MouseEvent): void;
133
  onDragEnd?(e: google.maps.MouseEvent): void;
134
  onDragStart?(e: google.maps.MouseEvent): void;
135
  onMouseDown?(e: google.maps.PolyMouseEvent): void;
136
  onMouseMove?(e: google.maps.PolyMouseEvent): void;
137
  onMouseOut?(e: google.maps.PolyMouseEvent): void;
138
  onMouseOver?(e: google.maps.PolyMouseEvent): void;
139
  onMouseUp?(e: google.maps.PolyMouseEvent): void;
140
  onRightClick?(e: google.maps.PolyMouseEvent): void;
141
}
142
```
143

144
**Usage Example:**
145

146
```javascript
147
import { Polygon } from "react-google-maps";
148

149
const trianglePath = [
150
  { lat: 25.774, lng: -80.190 },
151
  { lat: 18.466, lng: -66.118 },
152
  { lat: 32.321, lng: -64.757 },
153
  { lat: 25.774, lng: -80.190 }
154
];
155

156
<GoogleMap defaultZoom={5} defaultCenter={{ lat: 24.886, lng: -70.268 }}>
157
  <Polygon
158
    path={trianglePath}
159
    options={{
160
      fillColor: "#ff0000",
161
      fillOpacity: 0.35,
162
      strokeColor: "#ff0000",
163
      strokeOpacity: 0.8,
164
      strokeWeight: 2,
165
    }}
166
    editable={true}
167
    draggable={true}
168
    onClick={(event) => {
169
      console.log("Polygon clicked at vertex:", event.vertex);
170
    }}
171
  />
172
</GoogleMap>
173
```
174

175
### Polyline
176

177
Component for rendering line paths on the map, commonly used for routes and boundaries.
178

179
```javascript { .api }
180
/**
181
 * Polyline overlay component for drawing paths
182
 */
183
class Polyline extends Component<PolylineProps> {
184
  /** Returns whether the polyline is draggable */
185
  getDraggable(): boolean;
186
  /** Returns whether the polyline is editable */
187
  getEditable(): boolean;
188
  /** Returns the polyline's path */
189
  getPath(): google.maps.MVCArray<google.maps.LatLng>;
190
  /** Returns whether the polyline is visible */
191
  getVisible(): boolean;
192
}
193

194
interface PolylineProps {
195
  // Default props
196
  defaultDraggable?: boolean;
197
  defaultEditable?: boolean;
198
  defaultOptions?: google.maps.PolylineOptions;
199
  defaultPath?: google.maps.MVCArray<google.maps.LatLng> | Array<google.maps.LatLng | google.maps.LatLngLiteral>;
200
  defaultVisible?: boolean;
201
  
202
  // Controlled props
203
  draggable?: boolean;
204
  editable?: boolean;
205
  options?: google.maps.PolylineOptions;
206
  path?: google.maps.MVCArray<google.maps.LatLng> | Array<google.maps.LatLng | google.maps.LatLngLiteral>;
207
  visible?: boolean;
208
  
209
  // Event handlers
210
  onClick?(e: google.maps.PolyMouseEvent): void;
211
  onDblClick?(e: google.maps.PolyMouseEvent): void;
212
  onDrag?(e: google.maps.MouseEvent): void;
213
  onDragEnd?(e: google.maps.MouseEvent): void;
214
  onDragStart?(e: google.maps.MouseEvent): void;
215
  onMouseDown?(e: google.maps.PolyMouseEvent): void;
216
  onMouseMove?(e: google.maps.PolyMouseEvent): void;
217
  onMouseOut?(e: google.maps.PolyMouseEvent): void;
218
  onMouseOver?(e: google.maps.PolyMouseEvent): void;
219
  onMouseUp?(e: google.maps.PolyMouseEvent): void;
220
  onRightClick?(e: google.maps.PolyMouseEvent): void;
221
}
222
```
223

224
**Usage Example:**
225

226
```javascript
227
import { Polyline } from "react-google-maps";
228

229
const flightPath = [
230
  { lat: 37.772, lng: -122.214 },
231
  { lat: 21.291, lng: -157.821 },
232
  { lat: -18.142, lng: 178.431 },
233
  { lat: -27.467, lng: 153.027 }
234
];
235

236
<GoogleMap defaultZoom={3} defaultCenter={{ lat: 0, lng: -180 }}>
237
  <Polyline
238
    path={flightPath}
239
    options={{
240
      strokeColor: "#ff2527",
241
      strokeOpacity: 0.75,
242
      strokeWeight: 4,
243
    }}
244
    editable={true}
245
    onClick={(event) => {
246
      console.log("Polyline clicked at vertex:", event.vertex);
247
    }}
248
  />
249
</GoogleMap>
250
```
251

252
### Rectangle
253

254
Component for rendering rectangular overlays on the map.
255

256
```javascript { .api }
257
/**
258
 * Rectangular overlay component
259
 */
260
class Rectangle extends Component<RectangleProps> {
261
  /** Returns the rectangle's bounds */
262
  getBounds(): google.maps.LatLngBounds;
263
  /** Returns whether the rectangle is draggable */
264
  getDraggable(): boolean;
265
  /** Returns whether the rectangle is editable */
266
  getEditable(): boolean;
267
  /** Returns whether the rectangle is visible */
268
  getVisible(): boolean;
269
}
270

271
interface RectangleProps {
272
  // Default props
273
  defaultBounds?: google.maps.LatLngBounds | google.maps.LatLngBoundsLiteral;
274
  defaultDraggable?: boolean;
275
  defaultEditable?: boolean;
276
  defaultOptions?: google.maps.RectangleOptions;
277
  defaultVisible?: boolean;
278
  
279
  // Controlled props
280
  bounds?: google.maps.LatLngBounds | google.maps.LatLngBoundsLiteral;
281
  draggable?: boolean;
282
  editable?: boolean;
283
  options?: google.maps.RectangleOptions;
284
  visible?: boolean;
285
  
286
  // Event handlers
287
  onBoundsChanged?(): void;
288
  onClick?(e: google.maps.MouseEvent): void;
289
  onDblClick?(e: google.maps.MouseEvent): void;
290
  onDrag?(e: google.maps.MouseEvent): void;
291
  onDragEnd?(e: google.maps.MouseEvent): void;
292
  onDragStart?(e: google.maps.MouseEvent): void;
293
  onMouseDown?(e: google.maps.MouseEvent): void;
294
  onMouseMove?(e: google.maps.MouseEvent): void;
295
  onMouseOut?(e: google.maps.MouseEvent): void;
296
  onMouseOver?(e: google.maps.MouseEvent): void;
297
  onMouseUp?(e: google.maps.MouseEvent): void;
298
  onRightClick?(e: google.maps.MouseEvent): void;
299
}
300
```
301

302
**Usage Example:**
303

304
```javascript
305
import { Rectangle } from "react-google-maps";
306

307
const rectangleBounds = {
308
  north: 33.685,
309
  south: 33.671,
310
  east: -116.234,
311
  west: -116.251,
312
};
313

314
<GoogleMap defaultZoom={13} defaultCenter={{ lat: 33.678, lng: -116.243 }}>
315
  <Rectangle
316
    bounds={rectangleBounds}
317
    options={{
318
      fillColor: "#ff0000",
319
      fillOpacity: 0.35,
320
      strokeColor: "#ff0000",
321
      strokeOpacity: 0.8,
322
      strokeWeight: 2,
323
    }}
324
    editable={true}
325
    draggable={true}
326
    onBoundsChanged={() => {
327
      console.log("Rectangle bounds changed");
328
    }}
329
  />
330
</GoogleMap>
331
```
332

333
## Common Shape Styling Options
334

335
All shape components support common styling through the `options` prop:
336

337
```javascript
338
const shapeOptions = {
339
  fillColor: "#ff0000",        // Fill color
340
  fillOpacity: 0.35,           // Fill opacity (0-1)
341
  strokeColor: "#ff0000",      // Border color
342
  strokeOpacity: 0.8,          // Border opacity (0-1)
343
  strokeWeight: 2,             // Border width in pixels
344
  clickable: true,             // Whether shape responds to mouse events
345
  editable: false,             // Whether shape can be edited
346
  draggable: false,            // Whether shape can be dragged
347
  visible: true,               // Whether shape is visible
348
  zIndex: 1                    // Stacking order
349
};
350
```
351

352
## Interactive Editing
353

354
Enable interactive editing by setting `editable={true}`:
355

356
```javascript
357
<Polygon
358
  path={polygonPath}
359
  editable={true}
360
  onMouseUp={() => {
361
    // Handle edit completion
362
    const updatedPath = polygon.getPath().getArray();
363
    savePolygonPath(updatedPath);
364
  }}
365
/>
366
```