One of the key features in the alpha1 release of the iD map editor was its powerful support for labels. Labels are essential for orienting users and enabling them to find and fix misspellings and omissions. The technical challenge is to place labels quickly and avoid problems like overlapping text and visual clutter.

The basic goal of labeling is identify important features while avoiding overlapping labels. Because iD is an editor for a dynamic dataset, it also needs to handle labels which are updated by the user, hide labels so they don’t interfere with editing, and prioritize labeling features in the currently visible area. Traditional algorithms for automatic label placement use relatively complex simulated forces or annealing to find optimal label placements. In contrast, iD’s approach is simple, but effective for its editing-centric use.

First, iD collects and sorts all points, lines, areas in order of importance, based on their tagged attributes. For each of these potentially labeled features, the algorithm calculates possible positions for the label, iterating through different options to avoid conflicts with previously placed labels. In this way, it’s a fast greedy algorithm, and does run into scenarios in which it can’t place a label.

The set of possible label positions that are calculated for a feature depends on its type. For lines, labels must be shorter than the line and within the visible area. Line labels are flipped if necessary to ensure they do not appear upside-down. Area labels are placed only when they fit in the area’s bounding box. Point labels are currently simple: they’re always placed to the right of the point.

The labels are rendered using SVG. Point and area labels use text elements, whereas lines use textPath. Each label has a rect or path halo placed behind it to make the text readable on top of imagery and features. Labels are rendered on top of all other map features.

To keep editing fast and clear, labels are intelligently shown and hidden based on mouse position - so hovering near a road will fade out the label to reveal any hidden details.

Because labels are updated with each redraw of the map, they need to be extremely fast. iD calculates label bounding boxes based on estimated text length, since it’s slow to use browser-calculated bounds. We use RTree to optimize collision detection and proximity searches, a technique inspired by kothic.js.

Thanks to Vladimir and Tom for their suggestions.

iD’s labeling is robust and fast, but there’s still more work to do: we have a roadmap for further improvements that will be part of ongoing iD improvements.

Try it for yourself and take iD for a spin! If you find an area with poor labeling, please report it in an issue.



Devlogging work on the OpenStreetMap project by the MapBox team.

Much of this work is currently focused on improvements to OpenStreetMap funded by the Knight Foundation

Follow our work here on this blog or subscribe to our Twitter feed. You can subscribe to this blog’s feed or follow us at