Icons

Adding icons

You can add icons to the map via a style layer in the Style editor or via the addIcon() method:

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

The method takes as arguments the icon name and the StyleIconConfig options object containing the icon path.

Restrictions on using the method:

You can use only an absolute or template path to an icon as a URL, for example //absolute_path_to_icon/icon.svg or //{appHost}/path_to_icon/icon.svg.
You can use only an SVG image as an icon.

It is recommended to convert text in the SVG file to curves. Otherwise, if the client device does not have the font used in the SVG file, the text rendering may look different from the original icon.

<!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 previously added icon

To update a previously added icon, remove it and then add a new one:

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

To change an icon from the existing style, remove it and then add a new one:

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

Pass the current icon name used in the style. You can find the icon name in the Style editor.

<!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>