Playground: Symbol Layer
How to draw hundreds of points as icons with labels.
Marker and Popup places a Marker — an HTML element — on the map. That is convenient for a handful of points, but every marker is a DOM node the browser has to position on each frame, and markers know nothing about each other, so they happily overlap.
A symbol layer is the other approach: the points live in a source, MapLibre renders them together with the rest of the map, and one layer can carry thousands of them. This example draws 170 windmills and lighthouses from OpenStreetMap.
Icons
icon-image names an image in the style's sprite — a single sheet holding all icons. Our styles load the sprite basics, which contains around 110 images, all named icon-… (have a look).
Important
Our styles declare their sprite as a list, which means every image id carries the sprite's name as a prefix: basics:icon-windmill, not icon-windmill. Without the prefix MapLibre silently draws no icon at all.
Instead of a fixed id, this example builds the id from each feature's kind property:
'icon-image': ['concat', 'basics:icon-', ['get', 'kind']],
That is an expression: a small formula MapLibre evaluates per feature. ['get', 'kind'] reads a property, ['concat', …] glues strings together — so a windmill gets basics:icon-windmill and a lighthouse basics:icon-lighthouse. Almost every layout and paint property accepts expressions, which is what makes a single layer enough for differently styled features.
Labels
text-field works the same way; here it simply reads the name. Two properties around it are easy to get wrong:
text-fontmust name a font your glyph server actually has. We providenoto_sans_regularandnoto_sans_bold. MapLibre's default is a Mapbox font that we do not host, so leaving it out means no labels.text-anchorandtext-offsetmove the label off the icon — otherwise both are drawn at the same spot, on top of each other.
The halo (text-halo-color, text-halo-width) is what keeps labels legible over dark and light ground alike.
Collision handling
Zoom out and most labels disappear. MapLibre hides icons and labels that would overlap, keeping only what fits — which is why a symbol layer stays readable at any zoom while 170 markers would turn into a pile. Set icon-allow-overlap or text-allow-overlap to true if you would rather show everything.
All properties are listed in the Style Specification under symbol layers.