Overlay

The Overlay object is used to help with drawing overlays on the map.

Overlay extends Layer.

Examples of overlays include Popups and Tooltips.

The Overlay object creates a div element that is then populated with content and displayed on the map.

Creating the overlay

You can use the G.overlay() function to get your own overlay object.

G.overlay(): Overlay

const overlay = G.overlay();

Events

Below are the available overlay events

Event	Description
dragend	The event fired each time the dragging ends.
drag	The event fired each time the dragging updates the overlay position. This is called multiple times while the overlay is being dragged.
dragstart	The event fired when dragging the overlay starts.
open	The event fired when the overlay is opened.
resizeend	The event fired each time the resizing ends.
resize	The event fired each time the resizing updates the overlay size and position. This is called multiple times while the overlay is being resized.
resizestart	The event fired when resizing the overlay starts.

dragend

Called when the dragging the overlay ends.

overlay.on('dragend', () => {
    // Do something here
});

// You can also use the event constant
overlay.on(G.OverlayEvents.DRAG_END, () => {
    // Do something here
});

// Or, use the callback method
overlay.onDragEnd(() => {
    // Do something here
});

drag

Called when the dragging updates the overlay position.

overlay.on('dragstart', () => {
    // Do something here
});

// You can also use the event constant
overlay.on(G.OverlayEvents.DRAG, () => {
    // Do something here
});

// Or, use the callback method
overlay.onDrag(() => {
    // Do something here
});

dragstart

Called when the overlay is starting to be dragged.

overlay.on('dragstart', () => {
    // Do something here
});

// You can also use the event constant
overlay.on(G.OverlayEvents.DRAG_START, () => {
    // Do something here
});

// Or, use the callback method
overlay.onDragStart(() => {
    // Do something here
});

open

Called when the overlay is opened.

overlay.on('open', () => {
    // Do something here
});

// You can also use the event constant
overlay.on(G.OverlayEvents.OPEN, () => {
    // Do something here
});

// Or, use the onOpen method
overlay.onOpen(() => {
    // Do something here
});

resizeend

Called when the resizing the overlay ends.

overlay.on('resizeend', () => {
    // Do something here
});

// You can also use the event constant
overlay.on(G.OverlayEvents.RESIZE_END, () => {
    // Do something here
});

// Or, use the callback method
overlay.onDragEnd(() => {
    // Do something here
});

resize

Called when the resizing updates the overlay position.

overlay.on('resizestart', () => {
    // Do something here
});

// You can also use the event constant
overlay.on(G.OverlayEvents.RESIZE, () => {
    // Do something here
});

// Or, use the callback method
overlay.onDrag(() => {
    // Do something here
});

resizestart

Called when the overlay is starting to be resizeged.

overlay.on('resizestart', () => {
    // Do something here
});

// You can also use the event constant
overlay.on(G.OverlayEvents.RESIZE_START, () => {
    // Do something here
});

// Or, use the callback method
overlay.onDragStart(() => {
    // Do something here
});

Dragging the overlay

You can configure that the overlay can be dragged around the map by clicking on it and moving the mouse. If this is enabled then a border will be added to the overlay to make it easier to see the dimensions.

In order for the mouse events to apply to the overlay, the overlay will be added to a different layer on the Google map. By default the overlay is added to the overlayLayer pane. If dragging is enabled then it will be added to the float pane. This means that it will be above markers and polylines.

Resizing the overlay

You can configure that the overlay can be resized by dragging the corners. If this is enabled then resize handles will be added to the corners and a border will be added to the overlay.

In order for the mouse events to apply to the overlay, the overlay will be added to a different layer on the Google map. By default the overlay is added to the overlayLayer pane. If resizing is enabled then it will be added to the float pane. This means that it will be above markers and polylines.

Properties

Property	Type	Description
className	string	The class name for the overlay element.
drag	boolean	Whether the overlay can be dragged around the map.
offset	[Point]	The x/y offset for the overlay
position	LatLng	The latitude/longitude position of the overlay.
resize	boolean	Whether the overlay can be resized.
styles	object	An object of CSS styles that will be applied to the overlay element. This is for setting or retrieving all styles. If you need to set an individual style then use the style() method. This will merge the styles with the existing styles.

className

Get and set the class name of the overlay. If you need multiple class names then separate them with a space.

// Get the class name
const className = overlay.className;

// Set the class name
overlay.className = 'my-class-name';
// Set multiple class names
overlay.className = 'my-class-name another-class';

drag

Get or set whether the overlay can be dragged around the map.

// Get the drag value
const canDrag = overlay.drag;

// Set that the overlay is draggable
overlay.drag = true;
overlay.drag = false;

offset

Get and set the x/y offset for the overlay.

// Get the offset
const offset = overlay.offset;

// Set the offset
overlay.offset = G.offset([0, 10]);
// Or
overlay.offset = [0, 10];

position

Get and set the latitude/longitude position of the overlay.

// Get the position
const position = overlay.position.

// Set the poistion
overlay.position = G.latlng({ lat: 42.7, lng: -72.9 });
// Or
overlay.position = { lat: 42.7, lng: -72.9 };

resize

Get or set whether the overlay can be resized by dragging the corners.

// Get the resize value
const canResize = overlay.resize;

// Set that the overlay is resizable
overlay.resize = true;
overlay.resize = false;

styles

Get the inline styles for the overlay or bulk set multiple styles.

// Get the styles
const styles = overlay.styles;

// Set multiple styles
tooltip.styles = {backgroundColor: '#ff0000', color: '#fff'}

Methods

• Methods inherited from Layer.

constructor

constructor(objectType: string, testObject: string, testLibrary?: string)

The class object constructor.

Parameter	Type	Required	Description
objectType	string	Yes	The object type. i.e. "map", "marker", "tooltip". Used with the object type tests in Base.
testObject	string	Yes	The camel case object name that is used when testing for the existance of the Google Map library. This should be the name of the object that calls this method.
testLibrary	string		An optional Google maps library class to check for. This needs to be part of the google.maps object. If not set then it's set to testObject.

disableDrag

disableDrag(): Overlay

Disable dragging for this overlay.

overlay.disableDrag();

disableResize

disableResize(): Overlay

Disable resizing for this overlay.

overlay.disableResize();

display

display(map: Map): Promise<Overlay>

Add the overlay to the map and display it. This is an alias to show().

Parameter	Type	Required	Description
map	Map	Yes	The map object

overlay.display(map);

enableDrag

enableDrag(): Overlay

Enable dragging for this overlay.

overlay.enableDrag();

enableResize

enableResize(): Overlay

Enable resizing for this overlay.

overlay.enableResize();

getContainerLatLngFromPixel

Computes the geographical coordinates from pixel coordinates in the map's container.

This is a shortcut to getting the projection from the overlay and then calling fromContainerPixelToLatLng on the projection with the pixel value.

Parameter	Type	Required	Description
x	number | PointValue	Yes	The x pixel value, or a PointValue.
y	number		The y pixel value if x is a number.

const latLng = mapOverlay.getContainerLatLngFromPixel(xValue, yValue);
const latLng = mapOverlay.getContainerLatLngFromPixel({x: xValue, y: yValue});
const latLng = mapOverlay.getContainerLatLngFromPixel(G.point({x: xValue, y: yValue}));

getDivLatLngFromPixel

Computes the geographical coordinates from pixel coordinates in the div that holds the draggable map.

This is a shortcut to getting the projection from the overlay and then calling fromDivPixelToLatLng on the projection with the pixel value.

Parameter	Type	Required	Description
x	number | PointValue	Yes	The x pixel value, or a PointValue.
y	number		The y pixel value if x is a number.

const latLng = mapOverlay.getDivLatLngFromPixel(xValue, yValue);
const latLng = mapOverlay.getDivLatLngFromPixel({x: xValue, y: yValue});
const latLng = mapOverlay.getDivLatLngFromPixel(G.point({x: xValue, y: yValue}));

getOffset

getOffset(): Point

Get the offset value for the overlay. It returns a Point object.

const offset = overlay.getOffset();

getOverlayElement

getOverlayElement(): HTMLElement

Gets the overlay HTML element that was created in the constructor. The element is a div. This is the container for the content in the overlay.

const overlayElement = overlay.getOverlayElement();

getPosition

getPosition(): LatLng

Get the latitude/longitude position of the overlay. This is for when the overlay has a single latitude and longitude value for it's position and does not use latitude and longitude bounds.

const position = overlay.getPosition();

getProjection

getProjection(): google.maps.MapCanvasProjection

Gets the MapCanvasProjection object associated with this OverlayView.

The projection is not available until the overlay has been added to the map with setMap or show.

const projection = overlay.getProjection();

getResizeAspectRatio

getResizeAspectRatio(): number

Get the current aspect ratio for resizing

const ratio = overlay.getResizeAspectRatio();

hasPosition

hasPosition(): boolean

Returns whether the overlay has a latitude/longitude position set.

if (tooltip.hasPosition()) {
    // Do something
}

hide

hide(): Overlay

Hide the overlay.

overlay.hide();

move

move(position: LatLngValue, map?: Map): Promise<Overlay>

Move the overlay to a new position. If the overlay has not been displayed yet then this will display it.

Parameter	Type	Required	Description
position	LatLngValue	Yes	The latitude/longitude position value.
map	Map		The map object. If not set then an attempt is made to get the map object already assigned to the overlay.

overlay.move({ lat: 40.7, lng: -73.9 });

overlay.move({ lat: 40.7, lng: -73.9 }, map);

onDragEnd

onDragEnd(callback: EventCallback): void

Callback for when the dragging the overlay ends.

This is a convenience function for overlay.on(G.OverlayEvents.DRAG_END, callback).

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

Callback function parameters

Parameter	Type	Description
event	MouseEvent|TouchEvent	The browser mouse or touch event

overlay.onDragEnd((event, change) => {
    // Do something
    const newBounds = overlay.getBounds()
})

onDrag

onDrag(callback: EventCallback): void

Callback for when the dragging the overlay updates the overlay position. This is called multiple times while the overlay is being dragged.

This is a convenience function for overlay.on(G.OverlayEvents.DRAG, callback).

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

Callback function parameters

Parameter	Type	Description
event	MouseEvent|TouchEvent	The browser mouse or touch event
change	Point	The difference between the starting mouse position and the new mouse position.

overlay.onDrag((event, change) => {
    // Do something
})

onDragStart

onDragStart(callback: EventCallback): void

Callback for when the dragging the overlay starts.

This is a convenience function for overlay.on(G.OverlayEvents.DRAG_START, callback).

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

Callback function parameters

Parameter	Type	Description
event	MouseEvent|TouchEvent	The browser mouse or touch event

overlay.onDragStart((event) => {
    // Do something
})

onOpen

onOpen(callback: EventCallback): void

Callback for when the overlay is opened.

This is a convenience function for overlay.on(G.OverlayEvents.OPEN, callback).

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

There are no callback function parameters.

overlay.onOpen(() => {
    // Do something
})

onResizeEnd

onResizeEnd(callback: EventCallback): void

Callback for when the resizing the overlay ends.

This is a convenience function for overlay.on(G.OverlayEvents.RESIZE_END, callback).

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

Callback function parameters

Parameter	Type	Description
event	MouseEvent|TouchEvent	The browser mouse or touch event

overlay.onResizeEnd((event, change) => {
    // Do something
    const newBounds = overlay.getBounds()
})

onResize

onResize(callback: EventCallback): void

Callback for when the resizing the overlay updates the overlay position. This is called multiple times while the overlay is being resized.

This is a convenience function for overlay.on(G.OverlayEvents.RESIZE, callback).

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

Callback function parameters

Parameter	Type	Description
event	MouseEvent|TouchEvent	The browser mouse or touch event
corner	string	The corner that is the resizing is happening at. ne, nw, se, or sw.

overlay.onResize((event, corner) => {
    // Do something
})

onResizeStart

onResizeStart(callback: EventCallback): void

Callback for when the resizing the overlay starts.

This is a convenience function for overlay.on(G.OverlayEvents.RESIZE_START, callback).

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

Callback function parameters

Parameter	Type	Description
event	MouseEvent|TouchEvent	The browser mouse or touch event
corner	string	The corner that is the resizing is happening at. ne, nw, se, or sw.

overlay.onResizeStart((event, corner) => {
    // Do something
})

removeClassName

removeClassName(className: string): Overlay

Removes a class name from the overlay element.

Parameter	Type	Required	Description
className	string	Yes	The class name(s) to remove from the overlay element.

overlay.removeClassName('my-class');

If you need to remove multiple class names then separate them with a space.

overlay.removeClassName('my-class another-class');

setClassName

setClassName(className: string): Overlay

Set the class name(s) for the overlay element.

Parameter	Type	Required	Description
className	string	Yes	The class name(s) to set on the overlay element.

overlay.setClassName('my-class');

If you need to add multiple class names then separate them with a space.

overlay.setClassName('my-class another-class');

setMap

setMap(map: Map): Promise<Overlay>

Add the overlay to the map and display it. This is an alias to show().

Parameter	Type	Required	Description
map	Map	Yes	The map object

overlay.setMap(map);

setOffset

setOffset(offset: PointValue): Overlay

Set the x,y offset for the overlay. This lets you have the offset show a certain number of pixels from it's latitude/longitude position.

Parameter	Type	Required	Description
offset	PointValue	Yes	The x/y offset value.

overlay.setOffset([2, -3]);

setPosition

setPosition(position: LatLngValue): Overlay

Set the position of the overlay.

Parameter	Type	Required	Description
position	LatLngValue	Yes	The latitude/longitude position value.

overlay.setPosition({ lat: 40.7, lng: -73.9 });

setResizeAspectRatio

setResizeAspectRatio(aspectRatio: number): Overlay

Set the aspect ratio to maintain during resizing. If this is set then when the overlay is resized it will stay in that aspect ratio.

Parameter	Type	Required	Description
aspectRatio	number	Yes	The number after dividing width / height.

const aspectRatio = elementWidth / elementHeight;
overlay.setResizeAspectRatio(aspectRatio);

setStyles

setStyles(styles: object): Overlay

Set one more styles for thes overlay element. This will merge styles with an existing ones.

Parameter	Type	Required	Description
styles	object	Yes	Object of key => value pairs of CSS styles to set on the element.

overlay.setStyles({ backgroundColor: '#333', border: '2px solid #ff0000' });

show

show(map: Map): Promise<Overlay>

Add the overlay to the map and display it. This is an alias to setMap.

Parameter	Type	Required	Description
map	Map	Yes	The map object

overlay.show(map);

style

style(key: string, value: string): Overlay

Add a single style to the overlay wrapper div.

Parameter	Type	Required	Description
name	string	Yes	The style name. For example, color or backgroundColor.

overlay.style('padding', '3px 6px');

toggle

toggle(map: Map): void

Toggle the display of the overlay on the map.

Parameter	Type	Required	Description
map	Map	Yes	The map object

tooltip.toggle(map);