Controls

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

Copyright text is also considered a control element. According to the license agreement, the copyright must always be visible and not be covered by other elements.

Zoom control

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, specify one of the possible positions (see ControlPosition) as the value of zoomControl.

const map = new mapgl.Map('container', {
    ...
    zoomControl: '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: 'bottomLeft',
            });
        </script>
    </body>
</html>

Traffic control

Traffic control is a button that can be used to show the current traffic condition. To add this button to the map, specify the trafficControl parameter when creating a map with the required position or with the value true (default position).

const map = new mapgl.Map('container', {
    ...
    trafficControl: '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,
                trafficControl: 'topRight',
            });
        </script>
    </body>
</html>

Scale bar

Scale bar is not displayed by default. You can show it by setting the scaleControl parameter to true.

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

You can also change the position of the control. To do that, specify one of possible positions (see ControlPosition) as a value of scaleControl.

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

<!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="Scale bar 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',
                scaleControl: 'topLeft',
            });
        </script>
    </body>
</html>

Floor control

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, specify the floorControl parameter when creating a map with the required position or with the value true (default position).

const map = new mapgl.Map('container', {
    ...
    floorControl: '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],
                styleZoom: 18,
                rotation: -3,
                pitch: 45,
                key: 'Your API access key',
                floorControl: 'bottomLeft',
            });
        </script>
    </body>
</html>

Adding controls after map load

To add a control to an existing map, you need to create a corresponding object specifying the map instance and the required position:

mapgl.ZoomControl - zoom control;
mapgl.TrafficControl - traffic control;
mapgl.FloorControl - floor control;
mapgl.ScaleControl - scale bar.

For example, to add a floor control to the map instance, you can use the following code:

const floorControl = new mapgl.FloorControl(map, {
    position: 'bottomLeft',
});

Custom control

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>

Copyright position

To change the position of the copyright text, specify the copyright parameter when creating a map with the required position.

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

You can also change the padding of all control elements by calling the setControlsLayoutPadding() method. Padding is specified separately for each side.

For example, to increase the bottom padding if the copyright is covered from the bottom by another element, specify the bottom parameter when calling the method:

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>