Add a stretchable image to the map
Use a stretchable image as a background for text.
const map = new maplibregl.Map({
container: 'map',
style: 'https://demotiles.maplibre.org/style.json',
zoom: 0.1
});
const images = {
'popup': 'https://maplibre.org/maplibre-gl-js/docs/assets/popup.png',
'popup-debug':
'https://maplibre.org/maplibre-gl-js/docs/assets/popup_debug.png'
};
map.on('load', async () => {
const debugPopup = await map.loadImage(images['popup-debug']);
const popup = await map.loadImage(images['popup']);
map.addImage('popup-debug', debugPopup.data, {
// The two (blue) columns of pixels that can be stretched horizontally:
// - the pixels between x: 25 and x: 55 can be stretched
// - the pixels between x: 85 and x: 115 can be stretched.
stretchX: [
[25, 55],
[85, 115]
],
// The one (red) row of pixels that can be stretched vertically:
// - the pixels between y: 25 and y: 100 can be stretched
stretchY: [[25, 100]],
// This part of the image that can contain text ([x1, y1, x2, y2]):
content: [25, 25, 115, 100],
// This is a high-dpi image:
pixelRatio: 2
});
map.addImage('popup', popup.data, {
stretchX: [
[25, 55],
[85, 115]
],
stretchY: [[25, 100]],
content: [25, 25, 115, 100],
pixelRatio: 2
});
map.addSource('points', {
'type': 'geojson',
'data': {
'type': 'FeatureCollection',
'features': [
{
'type': 'Feature',
'geometry': {
'type': 'Point',
'coordinates': [40, -30]
},
'properties': {
'image-name': 'popup-debug',
'name': 'Line 1\nLine 2\nLine 3'
}
},
{
'type': 'Feature',
'geometry': {
'type': 'Point',
'coordinates': [40, 30]
},
'properties': {
'image-name': 'popup',
'name': 'Line 1\nLine 2\nLine 3'
}
},
{
'type': 'Feature',
'geometry': {
'type': 'Point',
'coordinates': [-40, -30]
},
'properties': {
'image-name': 'popup-debug',
'name': 'One longer line'
}
},
{
'type': 'Feature',
'geometry': {
'type': 'Point',
'coordinates': [-40, 30]
},
'properties': {
'image-name': 'popup',
'name': 'One longer line'
}
}
]
}
});
map.addLayer({
'id': 'points',
'type': 'symbol',
'source': 'points',
'layout': {
'text-field': ['get', 'name'],
'icon-text-fit': 'both',
'icon-image': ['get', 'image-name'],
'icon-overlap': 'always',
'text-overlap': 'always'
}
});
// the original, non-stretched image for comparison
map.addSource('original', {
'type': 'geojson',
'data': {
'type': 'FeatureCollection',
'features': [
{
'type': 'Feature',
'geometry': {
'type': 'Point',
'coordinates': [0, -70]
}
}
]
}
});
map.addLayer({
'id': 'original',
'type': 'symbol',
'source': 'original',
'layout': {
'text-field': 'non-stretched image',
'icon-image': 'popup-debug',
'icon-overlap': 'always',
'text-overlap': 'always'
}
});
});
<!DOCTYPE html>
<html lang="en">
<head>
<title>Add a stretchable image to the map</title>
<meta property="og:description" content="Use a stretchable image as a background for text." />
<meta property="og:created" content="2025-06-25" />
<meta charset='utf-8'>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel='stylesheet' href='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css' />
<script src='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.js'></script>
<style>
body { margin: 0; padding: 0; }
html, body, #map { height: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
const map = new maplibregl.Map({
container: 'map',
style: 'https://demotiles.maplibre.org/style.json',
zoom: 0.1
});
const images = {
'popup': 'https://maplibre.org/maplibre-gl-js/docs/assets/popup.png',
'popup-debug':
'https://maplibre.org/maplibre-gl-js/docs/assets/popup_debug.png'
};
map.on('load', async () => {
const debugPopup = await map.loadImage(images['popup-debug']);
const popup = await map.loadImage(images['popup']);
map.addImage('popup-debug', debugPopup.data, {
// The two (blue) columns of pixels that can be stretched horizontally:
// - the pixels between x: 25 and x: 55 can be stretched
// - the pixels between x: 85 and x: 115 can be stretched.
stretchX: [
[25, 55],
[85, 115]
],
// The one (red) row of pixels that can be stretched vertically:
// - the pixels between y: 25 and y: 100 can be stretched
stretchY: [[25, 100]],
// This part of the image that can contain text ([x1, y1, x2, y2]):
content: [25, 25, 115, 100],
// This is a high-dpi image:
pixelRatio: 2
});
map.addImage('popup', popup.data, {
stretchX: [
[25, 55],
[85, 115]
],
stretchY: [[25, 100]],
content: [25, 25, 115, 100],
pixelRatio: 2
});
map.addSource('points', {
'type': 'geojson',
'data': {
'type': 'FeatureCollection',
'features': [
{
'type': 'Feature',
'geometry': {
'type': 'Point',
'coordinates': [40, -30]
},
'properties': {
'image-name': 'popup-debug',
'name': 'Line 1\nLine 2\nLine 3'
}
},
{
'type': 'Feature',
'geometry': {
'type': 'Point',
'coordinates': [40, 30]
},
'properties': {
'image-name': 'popup',
'name': 'Line 1\nLine 2\nLine 3'
}
},
{
'type': 'Feature',
'geometry': {
'type': 'Point',
'coordinates': [-40, -30]
},
'properties': {
'image-name': 'popup-debug',
'name': 'One longer line'
}
},
{
'type': 'Feature',
'geometry': {
'type': 'Point',
'coordinates': [-40, 30]
},
'properties': {
'image-name': 'popup',
'name': 'One longer line'
}
}
]
}
});
map.addLayer({
'id': 'points',
'type': 'symbol',
'source': 'points',
'layout': {
'text-field': ['get', 'name'],
'icon-text-fit': 'both',
'icon-image': ['get', 'image-name'],
'icon-overlap': 'always',
'text-overlap': 'always'
}
});
// the original, non-stretched image for comparison
map.addSource('original', {
'type': 'geojson',
'data': {
'type': 'FeatureCollection',
'features': [
{
'type': 'Feature',
'geometry': {
'type': 'Point',
'coordinates': [0, -70]
}
}
]
}
});
map.addLayer({
'id': 'original',
'type': 'symbol',
'source': 'original',
'layout': {
'text-field': 'non-stretched image',
'icon-image': 'popup-debug',
'icon-overlap': 'always',
'text-overlap': 'always'
}
});
});
</script>
</body>
</html>