Labels | MapGL | 2GIS Documentation

Labels

To add a single Label:

const label = new mapgl.Label(map, {
    coordinates: [55.31878, 25.23584],
    text: 'Your label text',
});
<!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="A single label 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 label = new mapgl.Label(map, {
                coordinates: [55.31878, 25.23584],
                text: 'Your label text',
            });
        </script>
    </body>
</html>

To add several labels you need to create Label instance for each label respectively:

const firstLabel = new mapgl.Label(map, {
    coordinates: [55.27414, 25.25757],
    text: 'First label',
});
const secondLabel = new mapgl.Label(map, {
    coordinates: [55.28925, 25.21161],
    text: 'Second label',
});
const thirdLabel = new mapgl.Label(map, {
    coordinates: [55.34418, 25.21534],
    text: 'Third label',
});
<!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="A several labels 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: 12,
                key: 'Your API access key',
            });
            const firstLabel = new mapgl.Label(map, {
                coordinates: [55.27414, 25.25757],
                text: 'First label',
            });
            const secondLabel = new mapgl.Label(map, {
                coordinates: [55.28925, 25.21161],
                text: 'Second label',
            });
            const thirdLabel = new mapgl.Label(map, {
                coordinates: [55.34418, 25.21534],
                text: 'Third label',
            });
        </script>
    </body>
</html>

To add a Label with multiline text, just use the line break symbol \n in the text string:

const label = new mapgl.Label(map, {
    coordinates: [55.31878, 25.23584],
    text: 'First line\nSecond line\nThird line',
});
<!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="A multiline label 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 label = new mapgl.Label(map, {
                coordinates: [55.31878, 25.23584],
                text: 'First line\nSecond line\nThird line',
            });
        </script>
    </body>
</html>

By default the center point of the label box placed in the geographical coordinates specified in LabelOptions. But you can change this behavior by passing an relativeAnchor and an offset options:

// The center center label placement, by default.
const defaultPlacement = new mapgl.Label(map, {
    coordinates: [55.32878, 25.23584],
    text: 'Default label placement',
});
// The right center label placement.
const rightCenterPlacement = new mapgl.Label(map, {
    coordinates: [55.32878, 25.24584],
    text: 'Right center placement',
    relativeAnchor: [0, 0.5],
});
// The left top label placement with offset.
const leftTopPlacement = new mapgl.Label(map, {
    coordinates: [55.30878, 25.22584],
    text: 'Left top placement and offset',
    offset: [-10, -10],
    relativeAnchor: [1, 1],
});
<!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>
        <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',
            });
            // The center center label placement, by default.
            const defaultPlacement = new mapgl.Label(map, {
                coordinates: [55.32878, 25.23584],
                text: 'Default label placement',
            });
            // The right center label placement.
            const rightCenterPlacement = new mapgl.Label(map, {
                coordinates: [55.32878, 25.24584],
                text: 'Right center placement',
                relativeAnchor: [0, 0.5],
            });
            // The left top label placement with offset.
            const leftTopPlacement = new mapgl.Label(map, {
                coordinates: [55.30878, 25.22584],
                text: 'Left top placement and offset',
                offset: [-10, -10],
                relativeAnchor: [1, 1],
            });

            // The markers below are only for visualizing the geo-coordinates of the labels.
            // You don't need them in common.
            const defaultPlacementAnchor = new mapgl.Marker(map, {
                coordinates: [55.32878, 25.23584],
                icon: 'https://docs.2gis.com/img/mapgl/anchor.svg',
                zIndex: 100,
            });
            const rightCenterPlacementAnchor = new mapgl.Marker(map, {
                coordinates: [55.32878, 25.24584],
                icon: 'https://docs.2gis.com/img/mapgl/anchor.svg',
                zIndex: 100,
            });
            const leftTopPlacementAnchor = new mapgl.Marker(map, {
                coordinates: [55.30878, 25.22584],
                icon: 'https://docs.2gis.com/img/mapgl/anchor.svg',
                zIndex: 100,
            });
        </script>
    </body>
</html>

To add halo to the label you need to set haloRadius and haloColor in the LabelOptions:

const label = new mapgl.Label(map, {
    coordinates: [55.27414, 25.25757],
    text: 'First label',
    color: '#0000ff',
    haloRadius: 2,
    haloColor: '#00ff0055',
});
<!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="A label with halo 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 label = new mapgl.Label(map, {
                coordinates: [55.31878, 25.23584],
                text: 'Label with halo',
                color: '#0000ff',
                haloRadius: 2,
                haloColor: '#00ff0055',
            });
        </script>
    </body>
</html>

There is an ability to use a stretchable image as background for text. Stretchable images allow some parts of the image to stretch while keeping other parts, such as corners, at a constant size. Set the LabelOptions image property to use the image as label background.

Let's add the label «Label with image» with background image from the plot below.

tooltip-big-plot.svg

const label = new mapgl.Label(map, {
    coordinates: [55.31878, 25.23584],
    text: 'Label with image',
    fontSize: 64,
    image: {
        url: 'https://docs.2gis.com/img/mapgl/tooltip-big.svg',
        size: [500, 250],
        // The two (blue) columns of pixels that can be stretched horizontally:
        //   - the pixels between x: 50 and x: 200 can be stretched
        //   - the pixels between x: 300 and x: 450 can be stretched.
        stretchX: [
            [50, 200],
            [300, 450],
        ],
        // The one (red) row of pixels that can be stretched vertically:
        //   - the pixels between y: 50 and y: 150 can be stretched
        stretchY: [[50, 150]],
        // padding like in CSS [top, right, bottom, left]:
        padding: [50, 50, 100, 50],
    },
});
<!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="A label with background image 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 label = new mapgl.Label(map, {
                coordinates: [55.31878, 25.23884],
                text: 'Label with image',
                fontSize: 64,
                image: {
                    url: 'https://docs.2gis.com/img/mapgl/tooltip-big.svg',
                    size: [500, 250],
                    // The two (blue) columns of pixels that can be stretched horizontally:
                    //   - the pixels between x: 50 and x: 200 can be stretched
                    //   - the pixels between x: 300 and x: 450 can be stretched.
                    stretchX: [
                        [50, 200],
                        [300, 450],
                    ],
                    // The one (red) row of pixels that can be stretched vertically:
                    //   - the pixels between y: 50 and y: 150 can be stretched
                    stretchY: [[50, 150]],
                    // padding like in CSS [top, right, bottom, left]:
                    padding: [50, 50, 100, 50],
                },
            });
        </script>
    </body>
</html>

Note, to display the intersections of the labels with a background image correctly, it's necessary to set a different zIndex for each label.

const bottomLabel = new mapgl.Label(map, {
    ...bottomLabelOptions,
    zIndex: 1,
});
const middleLabel = new mapgl.Label(map, {
    ...topLabelOptions,
    zIndex: 2,
});
const topLabel = new mapgl.Label(map, {
    ...middleLabelOptions,
    zIndex: 3,
});
<!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="Several labels with background image 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 bottomLabel = new mapgl.Label(map, {
                coordinates: [55.27878, 25.23884],
                text: 'Label with image',
                zIndex: 1,
                image: {
                    url: 'https://docs.2gis.com/img/mapgl/tooltip.svg',
                    size: [100, 50],
                    stretchX: [
                        [10, 30],
                        [50, 90],
                    ],
                    stretchY: [[10, 30]],
                    padding: [10, 10, 20, 10],
                },
            });
            const middleLabel = new mapgl.Label(map, {
                coordinates: [55.31878, 25.23584],
                text: 'First line\nSecond line\nThird line',
                zIndex: 2,
                image: {
                    url: 'https://docs.2gis.com/img/mapgl/tooltip@2x.png',
                    pixelRatio: 2,
                    size: [100, 50],
                    stretchX: [
                        [10, 30],
                        [50, 90],
                    ],
                    stretchY: [[10, 30]],
                    padding: [10, 10, 20, 10],
                },
            });
            const topLabel = new mapgl.Label(map, {
                coordinates: [55.36878, 25.23084],
                text: 'Label with debug image',
                zIndex: 3,
                image: {
                    url: 'https://docs.2gis.com/img/mapgl/tooltip-debug.svg',
                    size: [100, 50],
                    stretchX: [
                        [10, 30],
                        [50, 90],
                    ],
                    stretchY: [[10, 30]],
                    padding: [10, 10, 20, 10],
                },
            });
        </script>
    </body>
</html>