Controls | MapGL | 2GIS Documentation

Controls

Controls are buttons that are displayed on the map container, i.e., they do not move when you move the map.

Zoom control is a set of two buttons, a plus and a minus, that can be used to change the zoom level of the map.

Zoom control is displayed by default. You can hide it by setting the zoomControl parameter to false.

const map = new mapgl.Map('container', {
    ...
    zoomControl: false,
});

You can also change the position of the control. To do that, hide the control initially and then add it to the map by calling the ZoomControl() method and specifying the required position (see ControlPosition for the list of possible positions):

const map = new mapgl.Map('container', {
    ...
    zoomControl: false,
});
const zoomControl = new mapgl.ZoomControl(map, {
    position: 'bottomLeft',
});
<!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="Zoom control example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></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',
                zoomControl: false,
            });

            const zoomControl = new mapgl.ZoomControl(map, {
                position: 'bottomLeft',
            });
        </script>
    </body>
</html>

Traffic control is a button that can be used to show the current traffic condition. To add this button to the map, call the TrafficControl() method:

const trafficControl = new mapgl.TrafficControl(map, {
    position: 'topRight',
});
<!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="Traffic control example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></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',
                zoomControl: false,
            });

            const trafficControl = new mapgl.TrafficControl(map, {
                position: 'topRight',
            });
        </script>
    </body>
</html>

Floor control is a set of buttons that can be used to change the currently displayed floor of a building. To add this control to the map, you can set the floorControl parameter to true:

const map = new mapgl.Map('container', {
    ...
    floorControl: true,
});

Alternatively, to specify the position of the control, call the FloorControl() method:

const floorControl = new mapgl.FloorControl(map, {
    position: 'bottomLeft',
});
<!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="Floor control example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.278765, 25.197039],
                zoom: 18,
                rotation: -3,
                pitch: 45,
                key: 'Your API access key',
            });

            const floorControl = new mapgl.FloorControl(map, {
                position: 'bottomLeft',
            });
        </script>
    </body>
</html>

You can also create your own controls. To do that, call the Control() method and specify the HTML markup for the control:

const control = new mapgl.Control(map, '<button>Custom control</button>', {
    position: 'topLeft',
});

To add an event listener to the control, first call the getContainer() method to get the content of the control and then add the listener as usual:

control
    .getContainer()
    .querySelector('button')
    .addEventListener('click', (ev) => {
        alert('The custom button is clicked!');
    });
<!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="Custom control example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></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 control = new mapgl.Control(map, '<button>Custom control</button>', {
                position: 'topLeft',
            });
            control
                .getContainer()
                .querySelector('button')
                .addEventListener('click', () => {
                    alert('The custom button is clicked!');
                });
        </script>
    </body>
</html>

The position of the controls can be set when the map is initialized. For example:

const map = new mapgl.Map('container', {
    ...
    floorsControl: false, // do not add control
    trafficControl: true, // add control to default position
    copyright: 'bottomLeft', // set the position of the control manually
});

Important notice: according to the licensing agreement copyright must always be visible on the map and must not be covered by other elements.

If the controls are covered with additional content, then you can preserve their visibility by setting the indents with the setControlsLayoutPadding function. For example:

map.setControlsLayoutPadding({
    bottom: 80,
});
<!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="Copyright example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
            body {
                position: relative;
            }
            #custom-bar {
                position: absolute;
                bottom: 0;
                left: 0;
                right: 0;
                top: auto;
                margin: 10px;
                padding: 20px;
                border-radius: 4px;
                background-color: white;
                box-shadow: 0 0 10px rgba(0, 0, 0, 0.5);
                text-align: center;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <div>
            <div id="custom-bar">User Content</div>
        </div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.31878, 25.22584],
                zoom: 13,
                key: 'Your API access key',
            });

            map.setControlsLayoutPadding({
                bottom: 80,
            });
        </script>
    </body>
</html>