Polygons

Learn how to work with polygons on a map.

We'll cover the following

Polygons represent a two-dimensional plane enclosed by a closed path where a series of coordinates define the enclosed path. A polygon has at least three sides. A Polygon object is drawn with a stroke and a fill. We can define custom style options for the stroke and custom colors for the enclosed area of the polygon.

Add a polygon to a map

A polygon’s area may consist of several separate paths. Therefore, the Polygon object’s path property specifies an array of arrays, and in each array, we specify a distinct sequence of ordered LatLng coordinates.

The Polygon constructor takes in the PolygonOptions parameter. The PolygonOptions parameter defines the LatLng coordinates for the vertices and a style set that alters the polygon’s visual features.

PolygonOptions Parameters

All PolygonOptions parameters are optional since there are no required parameters. Here’s a list of all the optional PolygonOptions parameters that we can pass to the Polygon constructor:

Parameters

Type

Description

paths

MVCArray<LatLng> | Array<LatLng|LatLngLiteral> I MVCArray<MVCArray<LatLng>> | Array<Array<LatLng|LatLngLiteral>>

This parameter represents an ordered set of coordinates that form a closed loop defining the Polygon boundary. We can pass this set of coordinates as either simple LatLng arrays or an MVCArray of LatLng objects. We may have to provide an array of arrays for more complex polygons.

geodesic

boolean

The term geodesic refers to the shortest possible line between two points on a curved surface. If we set this parameter to true, then the Polygon path follows the curvature of the Earth. When we set it to false, the polygon's sides are rendered as straight, connected lines. By default, the geodesic value is set to false.

strokeColor

string

This parameter specifies a hexadecimal code for the color of the line stroke, like #FFFFFF.

strokeOpacity

number

This parameter specifies a numerical value between 0.0 and 1.0 that determines the opacity of the stroke line's color. By default, the strokeOpacity value is set to 1.0.

strokePosition

StrokePosition

This parameter specifies the direction of the stroke. The StrokePosition data type has three possible constant values—CENTER, INSIDE, and OUTSIDE. By default, the strokePosition value is set to CENTER.


The CENTER value centers the stroke on the polygon's path, rendering one half of the stroke on the inside and one half on the outside of the polygon. The INSIDE value renders the stroke inside the polygon, and the OUTSIDE value renders it outside the polygon.

strokeWeight

number

This parameter specifies the width of the line in pixels.

clickable

boolean

This parameter specifies whether the Polygon can handle mouse events. By default, the clickable value is set to true.

draggable

boolean

This parameter allows the user to drag the polygons across the map when it's set to true. The geodesic parameter can alter this dragging behavior. By default, the draggable value is set to false.

editable

boolean

When set to true, this parameter allows the user to edit the polygons by dragging the control points of the vertices and line segments. By default, the editable value is set to false.

fillColor

string

This parameter specifies a hexadecimal code for the fill color of the polygon, like #FFFFFF.

fillOpacity

number

This parameter specifies a numerical value between 0.0 and 1.0 that determines the opacity of the polygon's fill color. By default, the fillOpacity value is set to 0.35.

map

Map

This parameter specifies the map that will have polylines rendered on it.

visible

boolean

This parameter specifies whether the polygons are displayed on the map or not.

zindex

number

This parameter represents the overlay order in which different drawing objects are placed in front of each other. A smaller-value zIndex object comes in front of a larger-value zIndex object.

We can construct a Polygon object without any parameters, since all the parameters are optional. However, if we want to display a Polygon, the map and paths parameters are required, and the visible parameter value must be true.

We can either provide map, paths, and all other parameters during construction or provide them after construction using the setValues() method. The setMap() can also be used to update the map parameter after construction.

Here’s an example of how a Polygon object is constructed:

Press + to interact
const polygonObj = new google.maps.Polygon({
	paths: [
		{ lat: 25.774, lng: -80.19 }, // First vertice of the Bermuda Triangle at Miami, Florida (US)
		{ lat: 18.466, lng: -66.118 }, // Second vertice of the Bermuda Triangle at San Juan, Puerto Rico
		{ lat: 32.321, lng: -64.757 }, // Third vertice of the Bermuda Triangle at Bermuda (UK)
	],
	geodesic: true,
	strokeColor: "#FF0000",
	strokeOpacity: 1.0,
	strokePosition: google.maps.StrokePosition.CENTER,
	strokeWeight: 2,
	clickable: true,
	draggable: false,
	editable: false,
	fillColor: "#FF0000",
	fillOpacity: 0.35,
	map: map,
	visible: true,
	zIndex: 1,
});

In each path of coordinates, the first and last locations are usually the same so that the loop is complete. However, since polygons are closed areas, we do not need to provide the last set of coordinates. In this case, the API will automatically complete the polygon by drawing a stroke between the first and last locations.

Code example

In the following example, we create a simple polygon on a map that represents the Bermuda Triangle:

Console
Add a polygon
Here’s a brief explanation of the JavaScript file in the code widget above:


    

  • Line 8: We define a polygonCoords array, that defines the sequence of coordinates that form the path boundary of the Bermuda Triangle.
    • 

  • Line 9: We define the coordinates of Miami, the first checkpoint from where we’re going to start our path boundary.
    • 

  • Line 12: We again define the coordinates of Miami as the final stop of our path boundary. We perform this action to draw the last stroke from the last vertice to the first vertice to close the path boundary of the Bermuda Triangle.
    • 

  • Lines 15–23: We construct our Polygon object and assign it to the variable bermudaTriangle. Note that we have not provided the map parameter here, which means that the Bermuda Triangle will only be constructed and not displayed on the map.
    • 

  • Line 16: We provide the polygonCoords array to the paths parameter in the bermudaTriangle object’s constructor to designate our polygon’s boundary.
    • 

  • Line 20: We set the draggable property to true, which allows us to drag the polygon across the map.
    • 

  • Line 25: We use the setValues() method to set and render the polygon bermudaTriangle on the specified map object, map.
    • 



Remove a polygon


We can remove a polygon from the map by calling the setMap() method on  polygonObj and passing null as its argument:


polygonObj.setMap(null);



Code example


In the example below, we create a polyline object, bermudaTriangle, with a UI control that allows the user to remove the polygon from the map:


Console
Remove a polygon
Here’s a brief explanation of the HTML file:


    

  • Lines 8–11: We create a separate div element just above our map’s div element. In this separate div element, we create two input buttons, namely add-polygon on line 9 to add the polygon and remove-polygon on line 10 to remove the polygon.
    • 



Here’s a brief explanation of the JavaScript file:


    

  • Lines 1–2: We define two global variables, map and bermudaTriangle.
    • 

  • Line 11: We define the array polygonCoords. This defines the sequence of coordinates that form the path boundary of the Bermuda Triangle.
    • 

  • Line 18: We initialize our Polygon object, bermudaTriangle.
    • 

  • Lines 34–38: We define a function addPolygon() to add the polygon. When this function is called, the setMap() method on line 35 renders the bermudaTriangle polygon over the map.
    • 

  • Lines 40-44: We define a function removePolygon() to remove the polygon, and using the setMap() method on line 41, we set the map parameter to null, which removes the polygon from the map.
    • 

  • Line 30: We define an event listener that listens for a click event for the add-polygon button element and calls the addPolygon() method.
    • 

  • Line 31: We define an event listener that listens for a click event for the remove-polygon button element and calls the removePolygon() method.
    •