Mapbox GL JS
All docsMapbox GL JSGuidesAdaptive projections

Adaptive projections

Starting from v2.6, Mapbox GL JS supports multiple map projections. This feature allows you to create more accurate visualizations at every zoom level, and tell a better story with your data.

Map Projections

A map projection is a way to flatten the globe's surface onto a screen. Every projection distorts size, shape and/or distance in its own way, so it's important to pick the right projection for your data.

Nearly all web maps, including Mapbox GL JS up to v2.5, rely only on the Web Mercator projection. It’s simple and efficient, but it heavily distorts the size of geographic shapes on lower scales. For example, Greenland is visually the same size as Africa, even though it’s 14 times smaller.

Mapbox GL JS provides a variety of alternative map projections to address this, offering new options to minimize distortion for a particular use case while keeping other aspects of an interactive map intact. The available options include projections optimized for thematic world maps, and projections for representing specific regions (such as the contiguous U.S. or Alaska).

Use projections in Mapbox GL JS

As of the Mapbox GL JS v2.6 release, developers are able to define the projection to use for displaying their map. The new projections are compatible with existing tile sources and map styles. See this simple example to get started quickly, or explore all available projections in this more advanced example.

You can set the projection through the map constructor’s projection option, at runtime via the setProjection method, or by including the projection in your map style. By default, maps will be in the Mercator projection, as they have been in all previous versions of Mapbox GL JS.

What projections are available?

Developers can select any of the following options when defining a style (each projection is defined in more detail below):

  • Albers (albers)
  • Lambert conformal conic (lambertConformalConic)
  • Equal Earth (equalEarth)
  • Natural Earth (naturalEarth)
  • Winkel tripel (winkelTripel)
  • Equirectangular (equirectangular)
  • Mercator (mercator, the default)

See the Available projections section below for more information about each.

Define a projection as a Map constructor option

You can define a map projection when creating a Map instance using shorthand:

const map = new mapboxgl.Map({
    container: 'map',
    projection: 'naturalEarth'
});

For projections with additional options, use an Object representation:

const map = new mapboxgl.Map({
    container: 'map',
    projection: {
        name: 'albers',
        center: [41.33, 123.45],
        parallels: [30, 50]
    }
});

Set a projection at runtime

You can set or change the map’s projection after Map creation by using the setProjection method:

// Use shorthand with default parameters
map.setProjection('equalEarth');

// Or override the projection-specific options
map.setProjection({
    name: 'albers',
    center: [41.33, 123.45],
    parallels: [30, 50]
});

Define a projection in a style

You can define a projection in a map style:

const map = new mapboxgl.Map({
    style: {
        version: 8,
        name: 'My Projected Style',
        sources: {
            // ...
        },
        layers: [
            // ...
        ],
        projection: {
            name: 'equalEarth'
        }
    }
});

Important notes about using projections in a style:

  • A projection defined in a style must be an object. The string shorthand is not valid in a style specification.
  • If you define one projection in a style, and set a different one at runtime (either through the map’s constructor or setProjection), then the runtime projection will be used.
  • Calling map.setProjection(null) will revert from any runtime projection to the one defined in the style.

Define a projection’s center and parallels

Conic projections like albers and lambertConformalConic have special properties, parallels and center:

  • parallels: [latitude1, latitude2]: Distortion of area and shape is minimized by the projection in the region between these two lines of latitude. The parallels can be the same latitude.
  • center: [longitude, latitude]: The location used to match scale and bearing with mercator. The size and bearing at this location will always be the same as it would be in mercator at the same zoom. At low zoom levels, other locations may have distorted size and bearing.

For any projection besides Albers and Lambert Conic Conformal, the center and parallels properties will be ignored.

This example shows how to configure the Albers projection to center on the U.S. state of Alaska. These properties can also be defined in the setProjection method or in a style.

const map = new mapboxgl.Map({
    container: 'map',
    projection: {
        name: 'albers',
        center: [-154, 50],
        parallels: [55, 65]
    }
});

Get current map projection

Developers can get the current map’s projection using map.getProjection().

Behavior and limitations

Map “unskewing” on zoom

Alternate projections in Mapbox GL JS have a novel adaptive design that adjusts the projection as you zoom in to minimize distortion on higher zoom levels, gradually transitioning from the defined projection to Web Mercator (which is optimal on higher zooms). This behavior is a core part of the implementation and can’t be configured or turned off.

Querying

Map querying via map.queryRenderedFeatures() works in all projections.

3D

In Mapbox GL JS v2.6, 3D terrain, fog and Free Camera API cannot be used simultaneously with non-Mercator projections. We plan to resolve this in a future release.

Custom style layers

In Mapbox GL JS v2.6, CustomLayerInterface cannot be used simultaneously with non-Mercator projections. We plan to resolve this in a future release.

Zoom and bearing

For any camera zoom level and location, maps in different projections will be rendered at the same scale they would be rendered in Mercator.

The bearing in Mercator maps corresponds directly to the rotation of the map (north is up). In other projections, the concept of bearing is more complicated since the direction of north can be different at different points on the map:

  • At low zoom levels, the bearing corresponds to the direction of north at the center of the projection.
  • At high zoom levels, the bearing corresponds to the direction of north at the center of the screen.
  • At intermediate zoom levels, bearing transitions between the two meanings.

Projection background

The empty area around the world in alternate projections is rendered as transparent. There are no style properties to control its appearance yet — the only way to change it is with CSS background property on the map container.

Constraining interaction

Maximum bounds constraints work differently with alternate projections. Map panning and zooming is constrained in a way so that the center of the map doesn’t go beyond the specified geographic bounds, rather than the whole visible area. This is potentially subject to change in future versions.

Available projections

Albers

The Albers projection (defined as albers in the Mapbox GL JS API) is a conic, equal-area projection. As a conic projection, it can be configured with the center and parallels properties to define a region in which distortion is minimized.

By default, the Albers projection is centered on the mainland United States at [-96, 37.5] with the standard parallels [29.5, 45.5]. This “Albers USA” projection is commonly used for showing geographic data in which comparing state-level sizes is important, for example in U.S. elections. Notable users of the projection include U.S. Geographical Survey, U.S. Census Bureau, and National Atlas of the U.S.

By configuring center and parallels, a developer can get a similar view for any region on Earth. See the above section on using the center and parallels properties for an example of configuring conic projections.

Composite Albers projection (e.g. where Alaska and Hawaii are alongside the mainland U.S.) is not yet supported in Mapbox GL JS.

Equal Earth

The Equal Earth projection (defined as equalEarth in the Mapbox GL JS API) is a cylindrical, equal-area projection. This projection is a global projection which is appropriate for thematic mapping, especially when size comparisons or relative distance from the equator are needed for interpreting the geographic data.

A notable use of Equal Earth projection is thematic maps on global temperature anomalies by NASA.

Equirectangular

The Equirectangular (Plate Carrée) projection (defined as equirectangular in the Mapbox GL JS API) is a cylindrical, compromise projection in which positions on the map directly correspond to their longitude and latitude values.

This projection is the standard for global raster datasets, such as Celestia, NASA World Wind, and Natural Earth, and is useful when you need to display these datasets without any distortion.

Lambert conformal conic

The Lambert Conformal Conic projection (defined as lambertConformalConic in the Mapbox GL JS API) is a conic, conformal projection used for aeronautical charts and many regional mapping systems. It can be configured with the center and parallels properties to define a region in which distortion is minimized.

By default, this projection is centered on [0, 30] with the standard parallels [30, 30]. This projection preserves shapes and is appropriate for regional maps which need accurate shapes and angles (note that as with many other conformal projections, size distortion will increase towards the poles).

This projection is popular for aeronautical charts because straight lines on it approximate great circle routes between endpoints. Notable users include the European Environmental Agency, France, and also U.S. National Geodetic Survey for several U.S. states such as Tennessee.

Natural Earth

The Natural Earth projection (defined as naturalEarth in the Mapbox GL JS API) is a cylindrical, compromise projection. This projection is appropriate for global, thematic mapping.

The distinguishing characteristics of Natural Earth are that parallels on this projection are straight lines, and a pleasant rounded aesthetic.

Winkel tripel

The Winkel tripel projection (defined as winkelTripel in the Mapbox GL JS API) is a “modified azimuthal” projection. The “tripel” part of the name comes from its goal of minimizing distortion in three aspects: area, direction and distance.

Since it doesn’t perfectly preserve any one aspect, Winkel tripel is a compromise projection, but it is commonly regarded as one of the least distorted compromise projections. The National Geographic Society and many other educational institutions use Winkel tripel for global, thematic mapping.