Tooltips

There is no predefined method to create a tooltip (i.e., an element that shows when the cursor hovers over some other element) in MapGL API. To create a tooltip, you can use mouseover and mouseout listeners to display a custom element relative to the coordinates of the required object.

For example, to set a tooltip for a marker, you can add mouseover and mouseout event handlers to the marker:

marker.on('mouseover', (e) => {
    console.log('cursor entering the marker');
});
marker.on('mouseout', (e) => {
    console.log('cursor leaving the marker');
});

The main idea is to show an HTML element on mouseover and hide it on mouseout. To get the display coordinates for the element, you can use the event argument (see MapPointerEvent).

Do not forget to hide the tooltip initially and set its position to absolute or fixed. Additionally, you need to set the pointer-events property to none or add a small offset to the tooltip. Otherwise, it will be displayed right under the cursor, which will trigger the mouseout event and hide the tooltip.

Simple tooltip may look like this:

<style>
    #tooltip {
        padding: 20px 40px;
        background: #fff;
        display: none;
        position: fixed;
        pointer-events: none;
    }
</style>
<div id="tooltip">Hello, world!</div>

And the code that displays the tooltip may look like this:

const tooltipEl = document.getElementById('tooltip');

marker.on('mouseover', (event) => {
    // Offset in pixels
    const offset = 5;

    tooltipEl.style.top = `${event.point[1] + offset}px`;
    tooltipEl.style.left = `${event.point[0] + offset}px`;
    tooltipEl.style.display = 'block';
});

marker.on('mouseout', (e) => {
    tooltipEl.style.display = 'none';
});

You can find a full example below. Hover the cursor over the marker to see the tooltip.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Map API</title>
        <meta name="description" content="Example of a tooltip for a marker" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }

            #tooltip {
                padding: 20px 40px;
                background: #fff;
                box-shadow: 1px 1px 2px rgba(0, 0, 0, 0.2);
                border-radius: 4px;
                display: none;
                position: fixed;
                pointer-events: none;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <div id="tooltip">Hello, world!</div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.31878, 25.23584],
                zoom: 13,
                key: 'Your API access key',
            });
            const marker = new mapgl.Marker(map, {
                coordinates: [55.31878, 25.23584],
                icon: 'https://docs.2gis.com/img/mapgl/marker.svg',
            });
            const tooltipEl = document.getElementById('tooltip');

            marker.on('mouseover', (event) => {
                // Offset in pixels
                const offset = 5;

                tooltipEl.style.top = `${event.point[1] + offset}px`;
                tooltipEl.style.left = `${event.point[0] + offset}px`;
                tooltipEl.style.display = 'block';
            });

            marker.on('mouseout', (e) => {
                tooltipEl.style.display = 'none';
            });
        </script>
    </body>
</html>

You can also set tooltips for other types of objects. For example, to set a tooltip for a Polyline, you can use the same two events that were used in the marker tooltip example (mouseover and mouseout).

You can find a full example below. Hover the cursor over the polyline to see the tooltip.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Map API</title>
        <meta name="description" content="Example of a tooltip for a polyline" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }

            #tooltip {
                padding: 20px 40px;
                background: #fff;
                box-shadow: 1px 1px 2px rgba(0, 0, 0, 0.2);
                border-radius: 4px;
                display: none;
                position: fixed;
                pointer-events: none;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <div id="tooltip">Hello, world!</div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.31878, 25.23584],
                zoom: 13,
                key: 'Your API access key',
            });
            const polyline = new mapgl.Polyline(map, {
                coordinates: [
                    [55.28770929, 25.22069944],
                    [55.28976922, 25.25656786],
                    [55.33096795, 25.22007825],
                    [55.33302789, 25.25687836],
                ],
                width: 10,
                color: '#00b7ff',
            });
            const tooltipEl = document.getElementById('tooltip');

            polyline.on('mouseover', (event) => {
                // Offset in pixels
                const offset = 5;

                tooltipEl.style.top = `${event.point[1] + offset}px`;
                tooltipEl.style.left = `${event.point[0] + offset}px`;
                tooltipEl.style.display = 'block';
            });

            polyline.on('mouseout', (e) => {
                tooltipEl.style.display = 'none';
            });
        </script>
    </body>
</html>

Tooltips

Tooltip for a marker

Tooltip for a shape