Tooltips | MapGL | 2GIS Documentation

Tooltips

The tooltip is a common graphical user interface element. The user hovers the pointer/mouse cursor over a marker/geometry, without clicking it, and the tooltip may appear.

First of all, you should create a marker on the map. Follow instructions from the marker article.

Markers can emit events. So, you can add mouseover and mouseout event handlers to your marker:

// Will be triggered, when the cursor will be over the marker
marker.on('mouseover', (e) => {
    console.log('mouseover');
});

// Will be triggered, when the cursor will be out of the marker
marker.on('mouseout', (e) => {
    console.log('mouseout');
});

The main idea is to show a tooltip on mouseover and hide it on mouseout. Every event handler's callback accepts a single parameter — event, describing the event which has occurred with info like screen points (x, y) and coordinates (lng, lat) of the event.

Tooltip can be any HTML element with any CSS you want. You can create it dynamically or add into the document manually. In the example below we describe the simplest version of the tooltip:

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

Tooltip should be hidden by default and positioned absolutely or fixed. Such positioning is required to show a tooltip over the map.

Now you can upgrade mouseover and mouseout event handlers. On mouseover you can show the tooltip at the point, which can be taken from event parameter. On mouseout you can set display to none to hide the tooltip. Also, you need to set pointer-events to none, cause your tooltip will appear exactly under the mouse cursor and mouseout will be triggered. Another approach is to add a small offset to top and left in CSS to shift from the event point. You can use both of them for the best view.

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';
});

Your tooltip will be shown up while mouse cursor is over the marker.

This is the simplest example of the tooltip. You can add some logic for more clever positioning near screen borders, more CSS, etc.

So, you can show any HTML above the map with such approach.

Full example of creating a tooltip for a marker. Put your mouse 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 add a tooltip to any type of geometries. The approach the same as with markers: show tooltip on mouseover and hide it on mouseout.

Full example of creating a tooltip for a polyline. Put your mouse 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>