Migrate to Mapbox GL JS v2

Mapbox GL JS v2 enables 3D mapping with globe, terrain, customizable skies and atmosphere, a new camera, adaptive projections, and performance enhancements. New features include:

• Globe view: Mapbox GL JS v2 adds a fully 3D globe, rendering your map as a view of the planet from space.
• Atmospheric Styling: To enhance the visuals of globe and highly pitched 3D maps, Mapbox GL JS v2 adds individually customizable atmosphere properties including an atmospheric gradient, stars, and haze. These properties can increase realism or match a designer's aesthetic. Fog provides a sense of visual depth and improves performance by reducing the number of tiles loaded in the distance.
• 3D terrain: Mapbox GL JS v2 adds elevated terrain rendering. Existing layer types and APIs will continue to work with the new 3D terrain. The new Mapbox Raster Data API service provides raster terrain tiles for use with the new 3D terrain.
• Adaptive projections: Mapbox GL JS v2 supports multiple map projections that gently adapt to zoom level for maximum accuracy, allowing you to create better visualizations at any scale and tell a better story with your data.
• FreeCamera API: Mapbox GL JS v2 provides a new low-level camera API known as the FreeCamera API. The FreeCamera allows you to move and animate the camera location and camera target independently of each other.
• Improved performance: Compared to v1, Mapbox GL JS v2 improves load time by up to 50% and renders more tile content during camera animations. In benchmark tests, the median map load time improved by 30%. v2 also optimizes resource loading and task scheduling to leave more CPU resources available for your application.

Migration guide

Mapbox GL JS v2 is backwards-compatible and existing layers and APIs will continue to work as expected, but there are some things to be aware of before upgrading to v2.

• Mapbox GL JS v2 is distributed as an ES6 compatible JavaScript bundle compatible with all major modern browsers. If you transpile Mapbox GL JS, upgrading from v1 to v2 may require modifications to your bundler configuration. See Transpiling for detailed guidance.

• Mapbox GL JS v2 ends support for Internet Explorer 11. If you need to support Internet Explorer, consider using the Mapbox Static Images API for non-interactive maps or using the Mapbox Static Tiles API with another library (for example, Mapbox.js or Leaflet) for interactive maps.

• The default maxPitch is increased from 60° to 85°. This change will make it possible to view above the horizon when the map is fully pitched. We recommend adding a customizable sky with atmospheric styling. If the map's fog property is not set, the area above the horizon will be transparent to any pixels behind the map.

• A valid Mapbox access token is required to instantiate a Map object. Assign a token using mapboxgl.accessToken or in the Map constructor options. To create an account or a new access token, visit https://account.mapbox.com.

• The action that triggers a map load has changed. In v1, a map load would occur whenever a Map instance is created and the map requested Mapbox-hosted tile resources. In v2, a map load occurs whenever a Map instance is created regardless of whether the map requests any Mapbox-hosted tile resources. Before updating an existing implementation of GL JS to v2, review the pricing documentation.

Known issues

• High pitch: Two-finger rotate gestures may break for touch points above the horizon.
• Terrain + High pitch: The GeolocateControl is not rendered correctly on highly pitched views with terrain.
• Terrain: *-translate properties for symbol, circle, and fill-extrusion layers do not account for terrain height.
• Terrain: Tile level-of-detail may cause terrain height to flicker when switching zoom levels.
• Terrain: Paint properties update in steps at integer zoom levels.
• Terrain: The height map for over-zoomed tiles is not being retained.

To report new issues with Mapbox GL JS v2, create a bug report on GitHub.