Circles

The Google Maps JavaScript API includes a specific Circle class that makes it easier to create and maintain circles on the map.

Add a circle to a map

The Circle object is quite similar to a Polygon object. For both of them, we can define custom styles and behaviors. However, unlike a Polygon object, we provide a circle’s center and radius to the object constructor instead of the paths parameter.

The Circle constructor takes in the CircleOptions parameter that defines the LatLng coordinates of the circle’s center. This constructor also defines the size and style of the circle.

CircleOptions parameters

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

We can construct a Circle object without any parameters, since they are all optional. However, to display a Circle object, the map, center, and radius parameters are required, and the visible parameter value must be true. We can either provide the map, center, radius, 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 how a Circle object is constructed:

new google.maps.Circle({
	center: { lat: 41.878, lng: -87.629 }, // Coordinates of Chicago city
	radius: 100000, // Setting circle to 100 kilometers
	strokeColor: "#FF0000",
	strokeOpacity: 0.8,
	strokePosition: google.maps.StrokePosition.CENTER,
	strokeWeight: 2,
	clickable: true,
	draggable: false,
	editable: false,
	fillColor: "#FF0000",
	fillOpacity: 0.35,
	map: map,
	visible: true,
	zIndex: 1,
});

Code example

In the example below, we create circles representing populations of certain US cities on the map:

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

• Line 2: We define citymap, which is made up of several city objects, each specifying the LatLng coordinates and population of the respective city.
• Line 28: We define a for loop to iterate through each city and render circles on the map according to their respective populations.
• Lines 29–38: We declare a new Circle object and set the location coordinates from each city object as the center of the circle.
• Line 31: We take the square root of each city’s population and multiply that number by 100. The resulting value is then used as the radius of the corresponding circle.

Removing a circle

We can remove a circle from the map by calling the setMap() method on the circle object and passing null as its argument.

newCircle.setMap(null);

Code example

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

Here’s a brief explanation of the HTML file in the above code widget:

• Lines 8–11: We create a separate div element just above our map’s div element. We create two input buttons in this separate div element: add-circle on line 9 for adding a circle and remove-circle on line 10 for removing the circle.

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

• Lines 1–2: We define two global variables, map and newCircle.
• Lines 11–19: We initialize our Circle object, newCircle. We set the coordinates of New York as the center of the circle and 200 kilometers as the radius of the circle.
• Lines 27–31: We define a function addCircle() to add the circle. When this function is called, the setMap() method on line 28 renders newCircle over the map.
• Lines 33–37: We define a function removeCircle() to remove the circle, and using the setMap() method on line 34, we set the map parameter to null, which removes the circle from the map.
• Line 23: We define an event listener that listens for a click event for the add-circle button element and calls the addCircle() method.
• Line 24: We define an event listener that listens for a click event for the remove-circle button element and calls the removeCircle() method.