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 or StyleStretchableIconConfig options object containing the icon path.

Restrictions on using the method:

• You can use only an absolute path, a template path, or a data URL as an icon URL, for example //absolute_path_to_icon/icon.svg, //{appHost}/path_to_icon/icon.svg, or data:image/svg+xml;base64,....
• 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.

Stretchable icon

To make an icon stretch with its text, specify the original width and height of the SVG and define the stretchable areas with stretchX and stretchY. The fixed areas keep the corners unchanged, while the configured areas stretch. The text inside the icon is set with iconTextField, and iconTextPadding controls the padding around it:

This example uses a 40 × 30 px SVG background:

The stretchX and stretchY values are measured in pixels of the original image:

map.addIcon('bubble', {
    url: bubbleUrl,

    // Original image width
    width: 40,

    // Original image height
    height: 30,

    // Area that can be stretched horizontally — the blue strip in the diagram
    stretchX: [
        [10, 30], // all pixels where X ≥ 10 and X ≤ 30
    ],

    // Area that can be stretched vertically — the pink strip in the diagram
    stretchY: [
        [10, 20], // all pixels where Y ≥ 10 and Y ≤ 20
    ],
});

In the layer style, iconTextPadding: [6, 10, 6, 10] sets CSS-like padding around the text in [top, right, bottom, left] order.

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' });

Changing an in-style icon

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

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

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