A Beginner's Guide to the Google Maps API/

...

/

Polylines

Polylines

Learn how to add or remove polylines on a map.

We'll cover the following...

The Polyline object is used to draw connected lines on a map. It defines a linear overlay of line segments connected on the map. A Polyline is a list of LatLng locations on which line segments are drawn in an ordered sequence. They’re an excellent way to highlight paths or routes between specific points.

Add a polyline on a map

The Polyline constructor takes in the PolylineOptions parameter, which defines a set of line coordinates and visual style settings. Here’s an example of a Polyline drawn across the United States:

We draw Polyline objects as a collection of line segments on the map. We can specify custom styles for the stroke of the line within the PolylineOptions when constructing line segments.

PolylineOptions object parameters

A PolylineOptions object has no required parameters, but it does support the following optional parameters:

Parameters

Type

Description

path

MVCArray<LatLng> | Array<LatLng|LatLngLiteral>

This parameter represents an ordered set of coordinates that define the route of the Polyline. We can pass this set of coordinates as either a simple LatLng array or an MVCArray of LatLng objects.

geodesic

boolean

The term geodesic refers to the shortest possible line between two points on a curved surface. When we set this parameter to true, the polyline follows the curvature of the Earth. When we set it to false, the polyline is shown as a set of connected straight 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 line's color. By default, strokeOpacity value is set to 1.0.

strokeWeight

number

This parameter specifies the width of the line in pixels.

clickable

boolean

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

draggable

boolean

This parameter allows the user to drag the polylines 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 polylines by dragging the control points of the vertices and line segments. By default, the editable value is set to false.

icons

Array<IconSequence>

This parameter specifies the icons and images that will be rendered across the polyline.

map

Map

This parameter specifies the map on which we are going to render polylines.

visible

boolean

This parameter specifies whether the polyline is displayed on the map.

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 larger-value zIndex object.

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

We can either provide map, path, 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 Polyline is constructed:

const polylineObj = new google.maps.Polyline({
	path: [
		{ lat: 51.5072, lng: -0.1276 }, // Coordinates of London
		{ lat: 40.7128, lng: -74.006 }, // Coordinates of New York
	],
	geodesic: true,
	strokeColor: "#00FF00",
	strokeOpacity: 0.75,
	strokeWeight: 3,
	clickable: true,
	draggable: false,
	editable: false,
	icons: [
		{
			icon: {
				path: google.maps.SymbolPath.FORWARD_CLOSED_ARROW,
				strokeColor: "#0F0",
				fillColor: "#0F0",
				fillOpacity: 1,
			},
			offest: "100%",
		},
	], // Arrow icon on Seattle
	map: map,
	visible: true,
	zindex: 1,
});

We can render polylines on the map using the setMap method and passing the map object as a parameter, as shown below:

polylineObj.setMap(map);

Code Example

The example below creates a two-pixel-wide red polyline that shows a flight path between Seattle and Brisbane that passes through Fiji and Hawaii:

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


    

  • Line 8: We define a flightPlanCoordinates object that defines the flight plan coordinates for Brisbane to Seattle.
    • 

  • Line 15: We initialize a Polyline object called flightPath that takes the flightPlanCoordinates object as its path.
    • 

  • Line 17: We set the geodesic parameter of flightPath to true, which makes the polyline follow the curvature of the earth.
    • 

  • Line 18: We set the strokeColor parameter of flightPath to #FF0000, which renders a red-colored polyline on the map.
    • 

  • Lines 19–20: We set the strokeOpacity to 1.0 and strokeWeight to 2 to render a completely opaque polyline with a width of 2 pixels.
    • 

  • Line 23: We call the setMap method to render the flightPath polylines over the map.
    • 



Remove a polyline


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


flightPath.setMap(null);



Code example


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


Console
Remove a polyline
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.
    • 

  • Line 9 and 10: In this separate div element, we create two input buttons, namely: add-line for adding the polylines and remove-line for removing the polylines.
    • 



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


    

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

  • Line 11: We define a flightPlanCoordinates object that defines the flight plan coordinates for Brisbane to Seattle.
    • 

  • Line 18: We initialize a Polyline object called flightPath that takes the flightPlanCoordinates object as its path.
    • 

  • Lines 31–35: We define a function addLine() to add polylines. When this function is called, the setMap() method on line 32 renders the flightPath polylines over the map.
    • 

  • Lines 37–41: We define a function removeLine() to remove polylines. In the setMap() method on line 38, we set the map parameter to null, which removes the polylines from the map.
    • 

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

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