Adding icons

It often needs to add your icon after adding a style layer. You can do it using Style editor or the map API method:

map.addIcon('newIconName', { url: '//path_to_icon/icon.svg' });

As arguments it takes an icon name and its config StyleIconConfig, which defines icon path.

For now, there are some restrictions on using this method:

only an absolute or template path to an icon can be used as a URL. For example, //absolute_path_to_icon/icon.svg or //{appHost}/path_to_icon/icon.svg accordingly.

It is recommended to convert text blocks in the SVG file to outlines. Otherwise, the text rendering may look different if the font used in the SVG file is not found on the user's device.

<!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="Adding user icon 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.26961558517149, 25.20161682758841],
                zoom: 16,
                key: 'Your API access key',
            });

            const data = {
                type: 'FeatureCollection',
                features: [
                    {
                        type: 'Feature',
                        properties: {},
                        geometry: {
                            type: 'Point',
                            coordinates: map.getCenter(),
                        },
                    },
                ],
            };


            const source = new mapgl.GeoJsonSource(map, {
                data,
                attributes: {
                    purpose: 'icon',
                },
            });

            const layer = {
                id: 'my-point-layer',
                filter: [
                    'match',
                    ['sourceAttr', 'purpose'],
                    ['icon'],
                    true,
                    false,
                ],
                type: 'point',
                style: {
                    iconImage: 'custom',
                    iconWidth: 30,
                    iconPriority: 1000
                },
            };

            map.on('styleload', () => {
                map.addIcon('custom', { url: 'https://docs.2gis.com/img/mapgl/point-red.svg'});
                map.addLayer(layer);
            });
        </script>
    </body>
</html>

Changing a previous added icon

To change a previous added or existing icon you have to remove it first and then add a new one the same way:

map.removeIcon('newIconName');
map.addIcon('newIconName', { url: '//path_to_icon/new-icon.svg' });

<!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="Changing user icon 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.26961558517149, 25.20161682758841],
                zoom: 16,
                key: 'Your API access key',
            });

            const data = {
                type: 'FeatureCollection',
                features: [
                    {
                        type: 'Feature',
                        properties: {},
                        geometry: {
                            type: 'Point',
                            coordinates: map.getCenter(),
                        },
                    },
                ],
            };


            const source = new mapgl.GeoJsonSource(map, {
                data,
                attributes: {
                    purpose: 'icon',
                },
            });

            const layer = {
                id: 'my-point-layer',
                filter: [
                    'match',
                    ['sourceAttr', 'purpose'],
                    ['icon'],
                    true,
                    false,
                ],
                type: 'point',
                style: {
                    iconImage: 'custom',
                    iconWidth: 30,
                    iconPriority: 1000
                },
            };

            map.on('styleload', () => {
                map.addIcon('custom', { url: 'https://docs.2gis.com/img/mapgl/point-red.svg'});
                map.addLayer(layer);
                map.once('idle', () => {
                    map.removeIcon('custom');
                    map.addIcon('custom', { url: 'https://docs.2gis.com/img/mapgl/point-green.svg'});
                });
            });
        </script>
    </body>
</html>

Changing an in-style icon

You can change an icon for any style layer even if it has not been added by addLayer method. To do that, you have to know an icon name in the current style. The adding process is the same as described above:

map.removeIcon('metro_red_uae');
map.addIcon('metro_red_uae', { url: '//path_to_icon/new-metro_red_uae.svg' });

<!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="An example of changing icon in the current style" />
        <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.26961558517149, 25.20161682758841],
                zoom: 16,
                key: 'Your API access key',
            });

            map.once('idle', () => {
                map.removeIcon('metro_red_uae');
                map.addIcon('metro_red_uae', { url: 'https://docs.2gis.com/img/mapgl/point-red.svg'});
            });
        </script>
    </body>
</html>