With Mapbox Studio, it’s easy to make a map with labels on top. It’s a little more tricky to know when a particular label should render. We’ve done the hard work of keeping labels legible so you don’t have to.
The map can be displayed at any combination of zoom, bearing, and pitch - so it’s helpful to keep in mind the rules that determine label visibility.
To avoid overlapping labels, we create a bounding box around each label. As we render the label, the bounding box is checked against the bounding boxes of visible labels. If there’s collision, the label will not render.
In Mapbox Studio, you can visualize these bounding boxes and collisions. Enable Collision boxes in the Debug panel of the style editor and the collision box for each label will appear on the map. Green boxes are rendered, red boxes are suppressed due to a collision. The collision boxes are updated as labels appear and disappear because of new collisions.
Want to change which labels are rendered? Here are a few tips to keep in mind:
- Layers higher in the layer listing are considered more important. They will be rendered first.
- Within a layer, labels are rendered in the order they are defined in the data source.
- Collision detection only occurs within a single source. If your style has multiple sources that define layers, they may collide.
- Collision detection can be disabled per layer with the
text-allow-overlapandtext-ignore-placementproperties. - Symbol layer icons also contribute to the label bounding box.
- Labels placed along lines have a collision box for each character.