Migrate to Maplibre in JavaScript

Plotly.js v2.35.0 introduced a new set of trace types for maps with tile underlays:

• Choroplethmap
• Scattermap
• Densitymap

These traces replaced the Mapbox traces, Choroplethmapbox, Scattermapbox, and Densitymapbox, and use MapLibre as the map renderer rather than Mapbox.

The Mapbox traces, the layout.mapbox subplot, and the mapboxAccessToken config option were removed in Plotly.js v4, along with the plotly-mapbox.min.js partial bundle and the zoomInMapbox, zoomOutMapbox, and resetViewMapbox modebar buttons (use plotly-map.min.js and zoomInMap, zoomOutMap, resetViewMap). If you are upgrading to v4, follow the steps below first. See Migrating to Plotly.js v4 for the rest of the upgrade.

When switching to the new traces, keep an eye out for improved rendering performance, WebGL2 support, and over time, improved features in the Plotly map traces inherited from the MapLibre renderer, including projection support, globe views, terrain support, and support for modern mapping standards.

You can learn more about the motivations for this change in our announcement post.

As a result of removing Mapbox as the rendering engine, we're also removing the Mapbox branding from these trace names. This means that migrating from Mapbox traces to MapLibre traces will require some code changes in your projects.

1. Change trace names from *mapbox to *map. For any existing trace name ending in *mapbox, ensure you've removed the "box" suffix.
2. If in use, update layout.mapbox argument in your layout configuration to layout.map. The nested properties are identical in the new map traces, so no other changes should be required.
3. If in use, update mapbox_style to map_style.
4. Verify your map_style settings. With mapbox traces, we bundle basic, streets, outdoors, light, dark, satellite, and satellite-streets styles, using Mapbox styling. These style names are still available, but they now reference slightly different styles provided by other tools. The three Stamen styles (stamen-terrain, stamen-toner, and stamen-watercolor) are not available, because Stamen tiles are served by Stadia Maps and require an API key — pass the URL of a style definition to use them.
5. Remove mapboxAccessToken from your config, and any mapbox://styles/mapbox/... style URLs, neither of which is supported. Custom MapLibre and Mapbox JSON style URLs still work.

Note that Mapbox API keys are no longer required for Plotly-provided styles, but using external styles in your Plotly maps remains supported with the existing API.