Labels
Simple label
To add a Label to the map, specify the coordinates and text:
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>
Multiple labels
You can add multiple Labels to the map:
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>
Multiline label
To add a Label with multiple lines of text, use the newline character (\n) as a line break:
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>
Text alignment
By default, the text is centered on the specified coordinates. To change the alignment of the text, use the relativeAnchor and offset parameters (see LabelOptions for more details):
// Horizontal and vertical center (the default)
const defaultPlacement = new mapgl.Label(map, {
coordinates: [55.32878, 25.23584],
text: 'Default label placement',
});
// Middle-right alignment
const rightCenterPlacement = new mapgl.Label(map, {
coordinates: [55.32878, 25.24584],
text: 'Right center placement',
relativeAnchor: [0, 0.5],
});
// Top-left alignment with an 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>
<!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>
Background image
You can use a stretchable image as a text background. To do that, use the image parameter and define the stretchable areas by using the stretchX (stretchable horizontally) and stretchY (stretchable vertically) parameters:
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],
// Areas that can be stretched horizontally (blue)
stretchX: [
[50, 200], // all pixels where X ≥ 50 and X ≤ 200
[300, 450], // all pixels where X ≥ 300 and X ≤ 450
],
// Areas that can be stretched vertically (red)
stretchY: [
[50, 150], // all pixels where Y ≥ 50 and Y ≤ 150
],
// CSS-like padding for text
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>
If you use multiple Labels with background images, it is important to set different zIndex for each Label so that the images can be correctly overlapped:
const bottomLabel = new mapgl.Label(map, {
...
zIndex: 1
});
const middleLabel = new mapgl.Label(map, {
...
zIndex: 2
});
const topLabel = new mapgl.Label(map, {
...
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],
[70, 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],
[70, 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],
[70, 90],
],
stretchY: [[10, 30]],
padding: [10, 10, 20, 10],
},
});
</script>
</body>
</html>