Creating map styles | MapGL | 2GIS Documentation
MapGL JS API

Creating map style

You can change the look of the map and its objects by applying styles. The style is a document that defines the visual appearance of the map: what data to draw, in what order, how to style the data when drawing it, what icons to draw, and more.

  1. Create your map style using one of the following tools:

    • Styles Editor, which allows you to configure the display of any map components in details. You can create your own style from scratch or use one of prepared templates. You can also edit the currently used style in the Editor.

      You can get all instructions on creating a style in the Style Editor documentation.

    • Style specification, which provides a reduced set (compared to the Styles Editor) of configurations. Use the specification if you want to change your map style in runtime (for example, add a new layer).

  2. Pass the ID of a created style via the style option:

    const map = new mapgl.Map('container', {
        center: [55.31878, 25.23584],
        styleZoom: 13,
        key: 'Your API access key',
        style: 'Your map style identifier',
    });
    

In the example above, the styleZoom option is used instead of zoom. Use it, if you want to set the same zoom that is used in the style settings. For details, see the Style zoom chapter.

Also, there is a convenient option defaultBackgroundColor with which you can set the background color while your style is loading. This can be really helpful when the new style has a different base color theme from the default style. For example, you can set the dark default background color for the dark style:

<!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="Style apply 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.187609, 25.141736],
                styleZoom: 16,
                pitch: 40,
                rotation: -45,
                key: 'Your API access key',
                style: 'e05ac437-fcc2-4845-ad74-b1de9ce07555',
                defaultBackgroundColor: '#3b3b3b',
            });
        </script>
    </body>
</html>

If you need to change the map style in runtime, you can use setStyleById method:

const map = new mapgl.Map('container', {
    center: [37.616723, 55.751],
    styleZoom: 13,
    key: 'Your API access key',
});

map.setStyleById('Your map style identifier');

This is about changing the map style as a whole, for example when switching between a light and dark theme:

<!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="Style apply in runtime example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
                font-family: Helvetica, Arial, sans-serif;
            }

            #dark_theme, #light_theme {
                margin: 0 10px 10px;
                padding: 3px 12px;
                background: #3b3b3b;
                color: #fff;
                border: none;
            }
        </style>
    </head>
    <body>
        <div>
            Click to switch theme:
            <button id="dark_theme">Switch to dark theme 🌙</button>
            <button id="light_theme">Switch to light theme 🌞</button>
        </div>

        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.187609, 25.141736],
                styleZoom: 16,
                pitch: 40,
                rotation: -45,
                key: 'Your API access key',
            });

            document.getElementById('dark_theme').addEventListener('click', function() {
                map.setStyleById('e05ac437-fcc2-4845-ad74-b1de9ce07555');
            });
            document.getElementById('light_theme').addEventListener('click', function() {
                map.setStyleById('c080bb6a-8134-4993-93a1-5b4d8c36a59b');
            });
        </script>
    </body>
</html>