Polyline

The Polyline object displays a single polyline on the map.

Polyline extends Layer.

Example usage

const polyline = G.polyline({
    map: map,
    path: [
        {lat: 48.1, lng: 2},
        {lat: 48.4, lng: 2.1},
        {lat: 48.6, lng: 1.8},
    ]
});

Creating the Polyline object

G.polyline(options?: PolylineValue): Polyline

There are a few ways that you can setup the Polyline object.

No parameters.

G.polyline(): Polyline

const polyline = G.polyline();

Pass the polyline options.

G.polyline(options: PolylineOptions): Polyline

Parameter	Type	Required	Description
options	PolylineOptions	Yes	The options.

const polyline = G.polyline({
    map: map,
    path: [
        {lat: 48.1, lng: 2},
        {lat: 48.4, lng: 2.1},
        {lat: 48.6, lng: 1.8},
    ]
});

Pass an existing Polyline object.

G.polyline(object: Polyline): Polyline

In this case the Polyline object is simply returned.

Parameter	Type	Required	Description
object	Polyline	Yes	A Polyline object.

const polyline = G.polyline(polylineObject);

Polyline value type

Any methods that accept a polyline value accepts PolylineValue as the value type.

The PolylineValue can be one of the following values:

Polyline object
PolylineOptions object

Custom data type

You can attach an object of data to the polyline object to hold some custom data. An example usage would be to include some content that you want to show in a popup when a polyline is clicked.

The CustomData type represents this data. Essentially it's an object that can hold any type of data

type CustomData = {
    [key: string]: any;
}

Polyline options

Type PolylineOptions

Option	Type	Default	Description
clickable	boolean	true	Whether the polyline handles click events.
dashed	boolean	false	Whether the polyline should display as a dashed line.
dashGap	string\|number	15px	The gap between each dash if the polyline is dispayed as a dashed line. The gap can be in pixels or a percentage of the dashed line's length. If only a number is passed then it's converted to pixels.
data	CustomData		An optional object to hold custom data to attach to the polyline object.
highlightPolyline	PolylineValue		The polyline to show below the existing one to create a "highlight" effect when the mouse hovers over this polyline. If an options object is passed then it's merged with this polyline's options, so you only need to set the options that are different. See Highlighting polylines for more information.
icons	PolylineIconValue\|PolylineIconValue[]		Any icons to show on the polyline.
map	Map		The map to add the polyline to.
path	LatLngValue[]		An array of LatLng values defining the path of the polyline on the map. Invalid values are ignored.
strokeColor	string		The polyline stroke color. All CSS3 colors are supported except for extended named colors.
strokeOpacity	number\|string	1	The polyline stroke opacity. The value should be between 0 and 1.0. A number string is converted to a number.
strokeWeight	number\|string	1	The polyline stroke width in pixels. A number string is converted to a number.
tooltip	TooltipValue		The tooltip for the polyline. This will show when hovering over the polyline.
visible	boolean	true	Whether the polyline is visible.
zIndex	number\|string		The zIndex compared to other polylines. A number string is converted to a number.

Events

Below are the available polyline events. All of the Google Maps polyline events can be used, along with the ready event from this library.

You can use the plain text name for the event, or you can use the event constant.

If the polyline has a highlight polyline, any event listener added with on() is also added to the highlight polyline so that mouse events on it behave the same as on this polyline. The ready event is not added to the highlight polyline. Removing a listener with off() also removes it from the highlight polyline.

Event	Description
click	The DOM click event is fired on the polyline.
contextmenu	The DOM contextmenu event is fired on the polyline.
dblclick	The DOM dblclick event is fired on the polyline.
drag	Fired repeatedly while the user drags the polyline.
dragend	The user stops dragging the polyline.
dragstart	The user starts dragging the polyline.
mousedown	The DOM mousedown event is fired on the polyline.
mousemove	The DOM mousemove event is fired on the polyline.
mouseout	The mouse leaves the polyline.
mouseover	The mouse enters the polyline.
mouseup	The DOM mouseup event is fired on the polyline.
ready	The polyline is loaded and ready for use.

polyline.on('click', (e) => {
    // Do something when the polyline is clicked
});

// You can use the event constant
polyline.on(G.PolylineEvents.MOUSE_OVER, (e) => {
    // Do something
});

ready

polyline.on('ready', () => {
    // Do something
});

// You can use the event constant
polyline.on(G.PolylineEvents.READY, () => {
    // Do something
});

// Or, use the onReady method
polyline.onReady(() => {
    // Do something
});

Properties

Properties inherited from Layer.

Property	Type	Description
clickable	boolean	Whether the polyline handles click events.
data	CustomData	An object that holds custom data to attach to the polyline object.
dashed	boolean	Whether the polyline should display as a dashed line.
dashGap	string\|number	The gap between each dash if the polyline is dispayed as a dashed line. The gap can be in pixels or a percentage of the dashed line's length. If only a number is passed then it's converted to pixels. The value is always returned as a string, like `'15px'`.
highlightPolyline	PolylineValue	The polyline to show below the existing one to create a "highlight" effect when the mouse hovers over this polyline. It can be set with a `Polyline` object or with polyline options, but it's always returned as a `Polyline` object. See Highlighting polylines for more information.
icons	PolylineIconValue\|PolylineIconValue[]	Any icons to show on the polyline. The value is always returned as an array of PolylineIcon objects.
map	Map\|null	The map to add the polyline to. Set to `null` to remove the polyline from the map.
path	LatLngValue[]	An array of LatLng values defining the path of the polyline on the map.
strokeColor	string	The polyline stroke color. All CSS3 colors are supported except for extended named colors.
strokeOpacity	number\|string	The polyline stroke opacity. The value should be between 0 and 1.0. The value is always returned as a number.
strokeWeight	number\|string	The polyline stroke width in pixels. The value is always returned as a number.
visible	boolean	Whether the polyline is visible.
zIndex	number\|string	The zIndex compared to other polylines. The value is always returned as a number.

Methods

Methods inherited from Layer.
Methods inherited from Evented.
Methods inherited from Base.

clone

clone(): Polyline

Clones the polyline object. The clone includes the polyline options, the custom data, the map, any attached tooltip, and a clone of the highlight polyline if one is set.

const copy = polyline.clone();

getData

getData(key?: string): any

Gets either all the custom data attached to the polyline object or the value for a specific data key from the custom data object.

If the key is specified but the value doesn't exist in the custom data object, then null is returned.

Parameter	Type	Required	Description
key	string	No	The object key to get a specific piece of data from the custom data obect. If this is not set then the entire custom data object is returned.

Get the entire data object.

const customData = polyline.getData();

Get a specific value from the custom data object.

const customValue = polyline.getData('dataKey');

hasZIndex

hasZIndex(): boolean

Returns whether the polyline has a zIndex set.

if (polyline.hasZIndex()) {
    // Do something
}

hide

hide(): Polyline

Hide the polyline. If a "highlight polyline" is set then that is also hidden.

This sets the visible property to false. It does not remove the polyline from the map.

polyline.hide();

highlight

highlight(options?: PolylineOptions): Polyline

Display the highlight polyline if it exists. See Highlighting polylines for more information.

Parameter	Type	Required	Description
options	PolylineOptions		The polyline options to override the existing highlight polyline options.

Nothing happens if the polyline doesn't have a highlight polyline or if the polyline is hidden.

polyline.highlight();

You can override the current highlight options by passing in the options parameter. This allows you to override one or more of the following options:

clickable
dashed
dashGap
icons
strokeColor
strokeOpacity
strokeWeight
zIndex

When the polyline is unhighlighted, the original options will be restored.

polyline.highlight({strokeColor: 'blue'});

onReady

onReady(callback: EventCallback): void

Callback for when the polyline is loaded and ready for use.

Parameter	Type	Required	Description
callback	Function	Yes	The callback function that will be called when the event is dispatched.

polyline.onReady(() => {
    // Do something
})

setDashed

setDashed(dashed: boolean, dashGap?: string|number): Polyline

Sets whether the polyline should be a dashed line.

This also lets you set the dash gap at the same time. The dash gap is only set if dashed is true.

Parameter	Type	Required	Description
dashed	boolean	Yes	Whether the polyline should display as a dashed line.
dashGap	string\|number		The gap between each dash if the polyline is dispayed as a dashed line. The gap can be in pixels or a percentage of the dashed line's length. If only a number is passed then it's converted to pixels.

// Change a dashed line to a solid line.
polyline.setDashed(false);

// Set a polyline to be dashed
polyline.setDashed(true);

// Set a polyline to be dashed and set the dash gap to 20px
polyline.setDashed(true, 20);

setDashGap

setDashGap(gap: string|number): Polyline

Set the gap between dashes when a polyline is displayed as dashes.

Parameter	Type	Required	Description
gap	string\|number	Yes	The gap between each dash if the polyline is dispayed as a dashed line. The gap can be in pixels or a percentage of the dashed line's length. If only a number is passed then it's converted to pixels.

// Pass a number only. This is the same as passing '20px'
polyline.setDashGap(20);

// Set a specific pixel value
polyline.setDashGap('18px');

// Set a percentage of the dashed line's length
polyline.setDashGap('10%');

setHighlightPolyline

setHighlightPolyline(value: PolylineOptions | Polyline): Polyline

Set up a version of the polyline to show when hovering over the polyline to give it a "highlight" effect. See Highlighting polylines for more information.

Parameter	Type	Required	Description
value	PolylineValue	Yes	The highlight polyline options or the highlight polyline object. If options are passed then they are merged with this polyline's options, so you only need to set the options that are different.

polyline.setHighlightPolyline({
    strokeColor: 'purple',
    strokeOpacity: 0.5,
    strokeWeight: 4,
});

setIcons

setIcons(value: PolylineIconValue|PolylineIconValue[]): Polyline

Set the icons for the polyline.

You can pass a single icon value or an array of icon values. Each icon value can be an object containing the icon options or a SvgSymbol object.

Parameter	Type	Required	Description
value	PolylineIconValue\|PolylineIconValue[]	Yes	Any icons to show on the polyline.

polyline.setIcons([
    G.svgSymbol({
        path: G.SymbolPath.CIRCLE,
        strokeColor: '#000000',
        scale: 2
    }),
    {
        icon: {
            path: "M -2,-2 2,2 M 2,-2 -2,2",
            strokeColor: "#22229B",
            strokeWeight: 4,
        }, 
        offset: '100%'
    }
]);

setMap

setMap(value: Map|null, isVisible?: boolean): Promise<Polyline>

Add the polyline to the map and display it. Pass null to remove the polyline from the map.

If the polyline has a highlight polyline then the map is set on it as well.

Parameter	Type	Required	Description
value	Map\|null	Yes	The map object. Set to `null` to remove the polyline from the map.
isVisible	boolean		Whether the polyline is visible on the map. Defaults to `true`.

polyline.setMap(map);

// Set the map but don't show the polyline
polyline.setMap(map, false);

// Remove the polyline from the map
polyline.setMap(null);

setOptions

setOptions(options: PolylineOptions): Polyline

Set the options for the polyline.

Parameter	Type	Required	Description
options	PolylineOptions	Yes	The polyline options.

polyline.setOptions({
    path: path,
    map: map,
    strokeColor: 'red',
    strokeWeight: 3,
    zIndex: 2,
});

setPath

setPath(path: LatLngValue[]): Polyline

Set the path of the polyline.

Parameter	Type	Required	Description
path	LatLngValue[]	Yes	An array of LatLng values defining the path of the polyline on the map.

polyline.setPath([
    {lat: 48.1, lng: 2},
    {lat: 48.4, lng: 2.1},
    {lat: 48.6, lng: 1.8},
]);

setStrokeColor

setStrokeColor(strokeColor: string): Polyline

Set the SVG stroke color. All CSS3 colors are supported except for extended named colors.

Parameter	Type	Required	Description
strokeColor	string	Yes	The color value. All CSS3 colors are supported except for extended named colors.

polyline.setStrokeColor('#ff0000');

setStrokeOpacity

setStrokeOpacity(strokeOpacity: number|string): Polyline

Set the opacity of the stroke.

Parameter	Type	Required	Description
strokeOpacity	number\|string	Yes	The stroke opacity value between 0 and 1.0. A number string is converted to a number.

polyline.setStrokeOpacity(0.5);

setStrokeWeight

setStrokeWeight(strokeWeight: number|string): Polyline

Set the weight of the stroke in pixels.

Parameter	Type	Required	Description
strokeWeight	number\|string	Yes	The stroke weight value. A number string is converted to a number.

polyline.setStrokeWeight(2);

setVisible

setVisible(visible: boolean): Polyline

Set whether the polyline is visible on the map.

Parameter	Type	Required	Description
visible	boolean	Yes	Whether the polyline is visible on the map.

polyline.setVisible(true);

polyline.setVisible(false);

show

show(map?: Map): Promise<Polyline>

Show the polyline on the map. This will also set the map object if it's passed.

You don't need to pass the map object if the polyline has already been assigned to the map.

Parameter	Type	Required	Description
map	Map		The map object.

polyline.show();

polyline.show(map);

toGoogle

toGoogle(): Promise<google.maps.Polyline>

Returns the Google Maps Polyline object. It will be a promise value.

polyline.toGoogle().then((googlePolyline) => {
    // Do something with the Google polyline object
});

unhighlight

unhighlight(): Polyline

Hide the highlight polyline if it exists. See Highlighting polylines for more information.

polyline.unhighlight();

Example usage​

Creating the Polyline object​

Polyline value type​

Custom data type​

Polyline options​

Events​

ready​

Properties​

Methods​

clone​

getData​

hasZIndex​

hide​

highlight​

onReady​

setDashed​

setDashGap​

setHighlightPolyline​

setIcons​

setMap​

setOptions​

setPath​

setStrokeColor​

setStrokeOpacity​

setStrokeWeight​

setVisible​

show​

toGoogle​

unhighlight​