Adding a Hover Tooltip to a Polygon Layer in Mapbox GL JS

#mapbox #webdev #mapping #ux

Hover tooltips are a great way to enhance the UX of your web maps. When the user moves their mouse across a region, district, delivery zone, or any other polygon, the map can talk back — instantly showing what the user is pointing at.

At Mapbox, we just published an updated code example demonstrating this pattern, and it highlights one of the most common UX needs: a lightweight tooltip that follows the cursor and displays the properties of the polygon underneath. If you're designing thematic maps, dashboards, or interactive exploratory tools, this is a pattern worth adding to your toolkit.

Why this pattern matters

A hover-follow tooltip gives users:

Instant context without clicking
A smooth, responsive feel as users move the mouse across boundaries
A clean, focused UI (no permanent labels cluttering the map)
A natural interaction pattern for data-rich polygons

This approach uses a single popup that moves dynamically with the cursor, updating its content with the feature you're hovering.

Key Concepts (with snippet examples)

1. Create a single reusable popup

You don’t want a new popup on every movement — just one that updates.

const popup = new mapboxgl.Popup({
  closeButton: false,
  closeOnClick: false,
  offset: [0, -20]  // keeps tooltip above the cursor
});

Update the popup position + content on mousemove The new example uses map.addInteraction to target a specific polygon layer and update the tooltip as the cursor moves across it.

map.addInteraction('hover-tooltip', {
  type: 'mousemove',
  target: { layerId: 'polygon-fills' },
  handler: (e) => {
    const label = e.feature.properties.name;

    popup
      .setLngLat(e.lngLat)
      .setHTML(`<strong>${label}</strong>`)
      .addTo(map);
  }
});

This keeps the tooltip synced to the cursor while pulling feature properties on demand.

Hide the tooltip on mouseleave A tiny interaction detail that keeps your UI clean:

map.on('mouseleave', 'polygon-fills', () => {
  popup.remove();
});

See the full working example

These snippets illustrate the pattern, but the full example includes a real dataset, layer styling, and the complete interaction flow.

👉 Check out the latest Mapbox GL JS hover tooltip example:

https://docs.mapbox.com/mapbox-gl-js/example/hover-tooltip/

The example shows exactly how this pattern works in a realistic scenario — a polygon dataset that updates the tooltip in real time as you move the mouse pointer across the map.

Explore More UX Patterns

If you're building interactive maps—dashboards, analytics tools, administrative boundaries, or selection-based interfaces—you’ll find more great patterns across the Mapbox GL JS example gallery.