Map styles | Mapbox GL JS

You can use Mapbox GL JS to control many aspects of the map design, including styling custom data, tweaking your map's styling, adding fonts, creating data-driven visualizations, and more. You can use a map style designed by Mapbox's cartographers, such as Mapbox Standard, or create a custom map style by adjusting the map's colors, icons, and fonts to match your application's UI or company's brand.

guide

Getting started: Map styles

Learn how Mapbox styles work and get started developing your map.

chevron-right

There are two approaches to customizing the look of the map:

Update map features dynamically at runtime using Mapbox GL JS API. Lighten or darken the map based on the time of day, personalize icons and map colors based on your users’ activity, switch languages dynamically, or increase the size of labels based on user preferences to improve legibility.
Create a custom map style with Mapbox Studio. Upload data, build styles from scratch, and style groups of layers together using style components. Publish your custom style and load it into your application. If you update the underlying data or you edit and publish updates to the style in Mapbox Studio, those changes will be reflected in your application.

These approaches are not mutually exclusive. You can load a custom style and update map features from that custom style in your application at runtime.

book

Mapbox Studio Manual

These guides cover working with the map style at runtime. For more information on how to create a custom map style in Mapbox Studio, see the Mapbox Studio Manual.

Set a style

Across the Mapbox ecosystem, the appearance of the map is determined by the map style. A Mapbox style is a JSON object that defines exactly how to draw a map. It defines almost everything related to a map's appearance. In Mapbox GL JS, you can set the style of the map when creating the map instance or at any point afterwards.

Choose a style

The style you choose for your application should reflect how your users will interact with the map and what they will use your application for. If you are not sure what style is right for you, we recommend getting started with the carefully designed, all-purpose Mapbox Standard style.

Load a style

Mapbox GL JS’s Map class provides an embeddable map interface. You can embed the map on a webpage, allow users to manipulate it with standard gestures, and more.

book

Default style

If you don’t specify a style when initializing a map, Mapbox GL JS will use the Mapbox Standard style by default.

You can rely on the default Mapbox Standard style, load the style when you first initialize the map by including it in the style property of Map options, or at any time after the map has been initialized using Map setStyle method by providing a corresponding style URL.

Mapbox Standard

Mapbox Standard is the default style, and instantiating a Map without specifying any style means your map will use Mapbox Standard.

const map = new mapboxgl.Map({
  container: 'map',
  center: [-74.5, 40],
  zoom: 9
});

Classic style templates and custom styles

If you don’t use Mapbox Standard, you can load your style by setting the style property with your custom style URL.

const map = new mapboxgl.Map({
  container: 'map',
  style: '<STYLE_URL>',
  center: [-74.5, 40],
  zoom: 9
});

To use one of the Mapbox-owned styles, use one of the following values:

mapbox://styles/mapbox/standard
mapbox://styles/mapbox/streets-v12
mapbox://styles/mapbox/outdoors-v12
mapbox://styles/mapbox/light-v11
mapbox://styles/mapbox/dark-v11
mapbox://styles/mapbox/satellite-v9
mapbox://styles/mapbox/satellite-streets-v12
mapbox://styles/mapbox/navigation-day-v1
mapbox://styles/mapbox/navigation-night-v1

book

Use style JSON

Though less common, you can also use a JSON value instead of an URL to load a style if you've written your style JSON manually.

book

Switch styles at runtime

You can also change the style any time after initializing the map using the Map setStyle method. If you added any layers at runtime, you will need to re-add layers after the new style is loaded.

Configure a style

Depending on what map style you choose, you have different configuration options available to customize aspects of your style such as fonts, colors, and more.

Mapbox Standard

The underlying design paradigm to Mapbox Standard is different from what you know from the classic styles templates. We’re establishing the concept of a basemap; Mapbox Standard is the first Style to follow this paradigm. You can consider everything that is maintained by Mapbox (natural features, roads, buildings etc.) as the basemap into which you embed your custom layers. The difference between the basemap and custom layers is important because different styling rules apply to them.

To change the visual appearance of the Standard basemap, you need to use the setConfigProperty method. Mapbox Standard offers 6 configuration properties that can be used to change the appearance of the basemap using setConfigProperty:

Property	Type	Description
`showPlaceLabels`	`Bool`	Shows and hides place label layers.
`showRoadLabels`	`Bool`	Shows and hides all road labels, including road shields.
`showPointOfInterestLabels`	`Bool`	Shows or hides all POI icons and text.
`showTransitLabels`	`Bool`	Shows or hides all transit icons and text.
`lightPreset`	`String`	Switches between 4 time-of-day states: `dusk`, `dawn`, `day`, and `night`. Lights can also be fully customized beyond the presets using the Mapbox style specification.
`font`	`Array`	Defines font family for the style from predefined options. Options: `Alegreya`, `Alegreya SC`, `Asap`, `Barlow`, `DIN Pro`, `EB Garamond`, `Faustina`, `Frank Ruhl Libre`, `Heebo`, `Inter`, `League Mono`, `Montserrat`, `Poppins`, `Raleway`, `Roboto`, `Roboto Mono`, `Rubik`, `Source`, `Code Pro`, `Spectral`, `Ubuntu`, `Noto Sans CJK JP`, `Open Sans`, `Manrope`, `Source Sans Pro`, `Lato`

Here’s an example illustrating how to switch the 3D lights in the basemap from the default preset, day, to another preset, dusk.

map.on('style.load', () => {
  map.setConfigProperty('basemap', 'lightPreset', 'dusk');
});

Similarly, you can set other configuration properties of the Standard style such as showing POIs, place labels, or specific fonts:

map.on('style.load', () => {
  map.setConfigProperty('basemap', 'showPointOfInterestLabels', false);
});

Other options to customize your map using Mapbox Standard include configuring root properties or styling your custom data in custom layers such that it reflects your personal preferences. Note that all the configurations are also available in the Mapbox Studio.

For custom layers that you add to the Mapbox Standard basemap, all configuration options are defined in the Mapbox Style Specification.

example

setConfigProperty example

Use different configuration properties with Mapbox Standard Style.

chevron-right

Style imports

To work with styles like Mapbox Standard, we've introduced Style APIs that allow you to import other styles into the main style you display to your users. These styles will be imported by reference, so updates to them will be reflected in your main style without additional work needed on your side. For example, imagine you have style A and style B. The Style API will allow you to import A into B. Upon importing, you can set configurations that apply to A and adjust them at runtime. The configuration properties for the imported style A will depend on what the creator of style A chooses to be configurable. For the Standard style, 6 configuration properties are available for setting lighting, fonts, and label display options. To import a style, you need to add an imports property to your Style JSON. In the above example, you would add "imports" to your Style JSON for B to import style A and set various configurations as defined in style A in the schema root property.

...
"imports": [
    {
        "id": "A",
        "url": "STYLE_URL_FOR_A",
        "config": {
            "font": "Montserrat",
            "lightPreset": "dusk",
            "showPointOfInterestLabels": true,
            "showTransitLabels": false,
            "showPlaceLabels": true,
            "showRoadLabels": false
        }
    }
],
...

Classic style templates and custom styles

The configuration options for classic style templates and custom styles are defined in the Mapbox Style Specification. Note that all the configurations are also available in the Mapbox Studio.

Work with layers

You can use Mapbox GL JS API to add more styled data to the map at runtime. There are two key concepts to understand when preparing to add a layer to a style at runtime: layers and sources. Sources contain geographic data. They determine the shape of the features you’re adding to the map and where in the world they belong. Layers contain styling information. They determine how the data in a source should look on the map.

A layer is a styled representation of data of a single type (for example polygons, lines, or points) that make up a map style. For example, roads, city labels, and rivers would be three separate layers in a map. There are several layer types (for example fill, line, and symbol). You can read more about layers in the Mapbox Style Specification.

Most layers also require a source. The source provides map data that Mapbox GL JS can use with a style document to render a visual representation of that data. There are several source types (for example vector tilesets, GeoJSON, and raster data). You can read more about sources in the Mapbox Style Specification.

In Mapbox GL JS, the Map class exposes the entry point for all methods related to the style object including sources and layers.

Add a layer at runtime

To add a new layer to the map at runtime, start by adding a source using the Style’s addSource method. It is important that you add the source for a new layer after the map has loaded but before attempting to add the layer itself because the source is a required parameter for most layer types.

Then, you’ll use the addLayer method to add the layer to the style. When adding the style layer, you will specify:

A unique id that you assign to the new layer
The layer type (for example fill, line, or symbol)
What data to use by referencing a source
The appearance of the data by setting various properties (for example color, opacity, and language)

The sample code below illustrates how to add a GeoJSON source and then add and style a line layer that uses the data in that source.

map.on('style.load', () => {
  map.addSource('route', {
    type: 'geojson',
    data: {
      /* ... GeoJSON data ... */
    }
  });
  map.addLayer({
    id: 'route',
    type: 'line',
    source: 'route',
    paint: {
      'line-color': '#888',
      'line-width': 8
    }
  });
});

The exact available properties available when adding a source and layer varies by source type and layer type. Read more about source types and layer types below.

Update a layer at runtime

You can also update the style of any layer at runtime using the layer's unique layer ID and defining style properties. The sample code below illustrates how to get an existing layer by referencing a layer ID and updating the line-opacity value.

map.setPaintProperty('route', 'line-opacity', 0.9);

The exact available properties available when updating a layer varies by layer type. Read more about layer types below.

Specify order of a layer at runtime for Mapbox Standard

Mapbox Standard uses slots to specify where custom data layers can be added. Slots are predetermined locations in the Standard basemap where your layer can be inserted. To add custom layers in the appropriate location in the Standard basemap layer stack, Standard offers 3 carefully designed slots that you can leverage to place your layer. These slots will stay stable, and you can be sure that your own map won't break even as the basemap updates over time.

Slot	Description
`bottom`	Above polygons (land, landuse, water, etc.)
`middle`	Above lines (roads, etc.) and behind 3D buildings
`top`	Above POI labels and behind Place and Transit labels
not specified	Above all existing layers in the style

Here’s an example of how to assign a slot to a layer:

map.addLayer({ type: 'line', slot: 'middle' /* ... */ });

Make sure to use slot instead of layer id when inserting a custom layer into the Standard basemap. Layers within the same slot can be rearranged using the optional beforeId argument. This argument specifies the ID of an existing layer before which the new layer will be inserted, causing the new layer to appear visually underneath the specified layer. But, if the layers are in different slots, the beforeId argument is ignored, and the new layer is added to the end of the layers array.

book

Slots and performance-optimized layers reordering

During 3D globe and terrain rendering, GL JS aims to batch multiple layers together for optimal performance. This process might lead to a rearrangement of layers. Layers draped over globe and terrain, such as fill, line, background, hillshade, and raster, are rendered first. These layers are rendered underneath symbols, regardless of whether they are placed in the middle or top slots or without a designated slot.

example

Layer slot example

Add a new layer to a slot in the Mapbox Standard Style.

chevron-right

Specify order of a layer at runtime for other styles

Map styles contain many individual layers (for example roads, buildings, labels, and more). By default, when you add a new layer to the style, it is placed on top of all the other layers. You can specify where the new layer is positioned relative to existing layers with an additional argument to the addLayer method which specifies an existing layer below which the new one should go.

map.addLayer({ type: 'line' /* ... */ }, 'state-labels');

Remove a layer at runtime

You can remove a layer from a style using Style's removeLayer method.

map.removeLayer('route');

Source types

Vector

A vector source, VectorTileSource, is a vector tileset that conforms to the Mapbox Vector Tile format. A vector source contains geographic features (and their data properties) that have already been tiled. Learn more about the benefits of vector tilesets and how they work in the Vector tiles documentation. For vector tiles hosted by Mapbox, the "url" value should be of the form of mapbox://username.tilesetid.

map.addSource('terrain', {
  type: 'vector',
  url: 'mapbox://mapbox.mapbox-terrain-v2'
});

book

NOTE

All style layers that use a vector source must specify a "source-layer" value.

GeoJSON

A GeoJSON source, GeoJSONSource, is data in the form of a JSON object that conforms to the GeoJSON specification. A GeoJSON source is a collection of one or more geographic features, which may be points, lines, and polygons. Data must be provided via a "data" property, whose value can be a URL or inline GeoJSON.

map.addSource('polygon', {
  type: 'geojson',
  data: { type: 'Feature', geometry: { type: 'Polygon' /* ... */ } }
});

book

NOTE

See the format of the data used in the sample code above in the GeoJSON polygon example.

Raster

A raster source, RasterTileSource, is a raster tileset. For raster tiles hosted by Mapbox, the "url" value should be of the form mapbox://tilesetid.

map.addSource('openstreetmap', {
  type: 'raster',
  tiles: ['https://tile.openstreetmap.org/{z}/{x}/{y}.png'],
  tileSize: 256,
  attribution:
    '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
});

Raster DEM

A raster DEM source, which is a special case of RasterTileSource, contains elevation data and refers to Mapbox Terrain-DEM (mapbox://mapbox.mapbox-terrain-dem-v1), which is the only supported raster DEM source. It must be added with the type: "raster-dem.

map.addSource('dem', {
  type: 'raster-dem',
  url: 'mapbox://mapbox.mapbox-terrain-dem-v1'
});

Image

An image source, ImageSource, is an image that you supply along with geographic coordinates. Specify geographic coordinates in the "coordinates" array as [longitude, latitude] pairs so the map knows at what location in the world to place the image. Each coordinate pair in the "coordinates" array represents the image corners listed in clockwise order: top left, top right, bottom right, bottom left.

map.addSource('radar', {
  type: 'image',
  url: '/mapbox-gl-js/assets/radar.gif',
  coordinates: [
    [-80.425, 46.437],
    [-71.516, 46.437],
    [-71.516, 37.936],
    [-80.425, 37.936]
  ]
});

Layer types

Fill layer

A fill style layer renders one or more filled (and optionally stroked) polygons on a map. You can use a fill layer to configure the visual appearance of polygon or multipolygon features.

To add a fill layer, you need to first add a vector or GeoJSON source that contains polygon data. Then you can use the available properties in fill layer to customize its appearance (for example, the color, opacity, or pattern).

map.addLayer({
  id: 'maine',
  type: 'fill',
  source: 'maine',
  paint: {
    'fill-color': '#0080ff',
    'fill-opacity': 0.5
  }
});

example

Fill layer example

Add a polygon to a map with an optional stroked border using a GeoJSON source.

chevron-right

Line layer

A line style layer renders one or more stroked polylines on the map. You can use a line layer to configure the visual appearance of polyline or multipolyline features.

To add a line layer, you need to first add a vector or GeoJSON source that contains line data. Then you can use the available properties in line layer to customize the appearance of the layer (for example, the color, width, or dash pattern).

map.addLayer({
  id: 'route',
  type: 'line',
  source: 'route',
  layout: {
    'line-cap': 'round'
  },
  paint: {
    'line-color': 'red',
    'line-opacity': 0.8
  }
});

example

Line layer example

Add a line to a map using a GeoJSON source.

chevron-right

Symbol layer

A symbol style layer renders icon and text labels at points or along lines on a map. You can use a symbol layer to configure the visual appearance of labels for features in vector tiles.

To add a symbol layer, you need to first add a vector or GeoJSON source that contains point data. If you want to use icons in this layer, you also need to add images to the style before adding the layer. Then you can use the available properties in symbol layer to customize the appearance of the layer.

map.addLayer({
  id: 'city-label',
  type: 'symbol',
  source: 'labels',
  layout: {
    'text-field': ['get', 'city_name'],
    'text-size': 12
  }
});

example

Symbol layer example

Add labels with variable label placement to a map using a GeoJSON source.

chevron-right

Circle layer

A circle style layer renders one or more filled circles on a map. You can use a circle layer to configure the visual appearance of point or point collection features in vector tiles. A circle layer renders circles whose radii are measured in screen units.

To add a circle layer, you need to first add a vector or GeoJSON source that contains point data. Then you can use the available properties in circle layer to customize the appearance of the layer (for example, radius, color, or offset).

map.addLayer({
  id: 'park-volcanoes',
  type: 'circle',
  source: 'national-park',
  paint: {
    'circle-radius': 6,
    'circle-color': '#B42222'
  }
});

example

Circle layer example

Style circles with a data-driven property.

chevron-right

Fill extrusion layer

A fill-extrusion style layer renders one or more filled (and optionally stroked) extruded (3D) polygons on a map. You can use a fill-extrusion layer to configure the extrusion and visual appearance of polygon or multipolygon features.

To add a fill extrusion layer, you need to first add a vector or GeoJSON source that contains polygon data. Often you will want the data to contain a data property that you will use to determine the height of extrusion of each feature. This may be a physical height in meters or a way to illustrate a non-physical attribute of the area like population in Census blocks. Once you've added an appropriate source, you can use the available properties in fill-extrusion layer class to customize the appearance of the layer (for example, the height, opacity, or color).

map.addLayer({
  id: '3d-buildings',
  source: 'composite',
  'source-layer': 'building',
  filter: ['==', 'extrude', 'true'],
  type: 'fill-extrusion',
  paint: {
    'fill-extrusion-color': '#aaa',
    'fill-extrusion-height': ['get', 'height'],
    'fill-extrusion-base': ['get', 'min_height'],
    'fill-extrusion-opacity': 0.6
  }
});

example

Fill extrusion layer example

Display buildings in 3D using a fill extrusion layer.

chevron-right

Hillshade layer

A hillshade style layer, renders digital elevation model (DEM) data on the client-side.

The implementation only supports sources comprised of Mapbox Terrain RGB or Mapzen Terrarium tiles. Once you've added an appropriate source, you can use the available properties in hillshade layer to customize the appearance of the layer.

map.addSource('dem', {
  type: 'raster-dem',
  url: 'mapbox://mapbox.mapbox-terrain-dem-v1'
});
map.addLayer({
  id: 'hillshading',
  source: 'dem',
  type: 'hillshade'
});

example

Hillshade layer example

Add hillshading using Mapbox terrain DEM source.

chevron-right

Heatmap layer

A heatmap style layer renders a range of colors to represent the density of points in an area.

To add a heatmap layer, you need to first add a vector or GeoJSON source that contains point data. Then you can use the available properties in heatmap layer to customize the appearance of the layer.

map.addLayer({
  id: 'earthquakes-heat',
  type: 'heatmap',
  source: 'earthquakes',
  paint: {
    'heatmap-color': [
      'interpolate',
      ['linear'],
      ['heatmap-density'],
      0,
      'rgba(33,102,172,0)',
      0.2,
      'rgb(103,169,207)',
      0.4,
      'rgb(209,229,240)',
      0.6,
      'rgb(253,219,199)',
      0.8,
      'rgb(239,138,98)',
      1,
      'rgb(178,24,43)'
    ],
    'heatmap-radius': 20
  }
});

example

Heatmap layer example

Add a heatmap layer using a GeoJSON source with point data.

chevron-right

Raster layer

A raster style layer, renders raster tiles on a map. You can use a raster layer to configure the color parameters of raster tiles.

To add a raster layer, you need to first add a raster source. Then you can use the available properties in raster layer to customize the appearance of the layer.

map.addLayer({
  id: 'radar-layer',
  type: 'raster',
  source: 'radar',
  paint: {
    'raster-fade-duration': 0
  }
});

example

Raster layer example

Add a raster image to a map using an image source and a raster layer.

chevron-right

Background layer

The background style layer, covers the entire map. Use a background style layer to configure a color or pattern to show below all other map content. If the background layer is transparent or omitted from the style, any part of the map view that does not show another style layer is transparent.

You can use the available properties in background layer to customize the appearance of the layer.

map.addLayer({
  type: 'background',
  paint: {
    'background-color': 'blue',
    'background-opacity': 0.3
  }
});

Styling your layers

Work with expressions

In Mapbox GL JS, you can specify the value for any layout property, paint property, or filter as an expression. Expressions define how one or more feature property value or the current zoom level are combined using logical, mathematical, string, or color operations to produce the appropriate style property value or filter decision.

A property expression is any expression defined using a reference to feature property data. Property expressions allow the appearance of a feature to change with its properties. They can be used to visually differentiate types of features within the same layer or create data visualizations.

A camera expression is any expression defined using ['zoom']. Such expressions allow the appearance of a layer to change with the map’s zoom level. Zoom expressions can be used to create the illusion of depth and control data density.

There are countless ways to apply property expressions to your application, including:

Data-driven styling: Specify style rules based on one or more data attribute.
Arithmetic: Do arithmetic on source data, for example performing calculations to convert units.
Conditional logic: Use if-then logic, for example to decide exactly what text to display for a label based on which properties are available in the feature or even the length of the name.
String manipulation: Take control over label text with things like uppercase, lowercase, and title case transforms without having to edit, re-prepare and re-upload your data.

Mapbox Style Specification: Expressions

An expression defines a formula for computing the value of the property using the operators described in this section.

chevron-right

Expression syntax

The Mapbox GL JS expressions follow this format:

["expression_name", argument_0, argument_1]

The expression_name is the expression operator, for example, you would use "*" to multiply two arguments or case to create conditional logic.

The arguments are either literal (numbers, strings, or boolean values) or else themselves expressions. The number of arguments varies based on the expression.

Here's one example using an expression to calculate an arithmetic expression (π * 3²):

["*", ["pi"], ["^", 3, 2]]

This example uses the "*" operator to multiply two arguments. The first argument is pi, which is an expression that returns the mathematical constant Pi. The second arguement is another expression: a pow expression with two arguments of its own. It will return 3², and the result will be multiplied by π.

Expression types

Mathematical operators for performing arithmetic and other operations on numeric values
Logical operators for manipulating boolean values and making conditional decisions
String operators for manipulating strings
Data operators for providing access to the properties of source features
Camera operators for providing access to the parameters defining the current map view

Data-driven styling at runtime

You can use expressions to determine the style of features in a layer based on data properties in the source data. For example, if you have a source containing point data from individual responses to the 2010 U.S. Census and each point has an "ethnicity" data property, you can use expressions to specify the color of each circle based on reported ethnicity.

The example below uses the match operator to compare the value of the "ethnicity" data property for each point in the source to several possible values. The first argument of the match expression is the value of the "ethnicity" data property. There are several arguments that specify what to do if the value of the data property matches a given string and a final argument that specifies what to do if the value of the data property does not match any of the strings provided.

To read the values of the "ethnicity" data property, this example uses the get operator with "ethnicity" as the sole argument.

Then, it uses stops for the next several arguments for the match expression. Each stop has two arguments: the first is the value to compare to the value of the "ethnicity" data property and the second is the value that should be applied to the layer's circleColor property if the value of the data property matches the first argument.

The second argument of the stop is a color, which is constructed using the rgb operator.

The final argument of the match expression is a fallback value that should be applied to circle-color if the value of the "ethnicity" data property does not match any of the strings provided.

map.addLayer({
  id: 'circle',
  type: 'circle',
  source: 'census',
  paint: {
    // match the value of the data property to a specific color
    'circle-color': [
      'match',
      ['get', 'ethnicity'],
      'White',
      '#fbb03b',
      'Black',
      '#223b53',
      'Hispanic',
      '#e55e5e',
      'Asian',
      '#3bb2d0',
      /* other */ 'black'
    ]
  }
});

example

Data-driven styling example

Style circles with a data-driven property

chevron-right

Zoom-driven styling at runtime

You can use expressions to determine the style of features in a layer based on the camera position, including the zoom level. For example, if you have dense point data displayed using a circle layer, you may want to adjust the radius of circles based on the zoom level to make the data more readable at low zoom levels.

The example below uses the interpolate operator to produce a continuous, smooth series of values between pairs of input and output values ("stops"). Its first argument sets the interpolation type, the second is the value of the zoom level, and the remaining arguments specify the size of the circle radius that should be applied based on the value of the zoom level.

"Exponential" is one of a few types of interpolation available Mapbox expressions. An expression using the exponential operator has one argument: the base, which controls the rate at which the output increases.

The zoom expression does not require any arguments. It will return the value of the current zoom level of the map.

The remaining arguments of the interpolate expression are stops. They represent points along the exponential curve. When a user is viewing the map at zoom level 12 or below, the circles will have a radius of 2. When viewing it at zoom level 22 and above, the circles will have a radius of 180. For all zoom levels between, the radius will be determined by an exponential function and the value will fall somewhere between 2 and 180.

map.addLayer({
  id: 'population',
  type: 'circle',
  source: 'ethnicity-source',
  'source-layer': 'sf2010',
  paint: {
    'circle-radius': [
      // Produce a continuous, smooth series of values
      // between pairs of input and output values
      'interpolate',
      ['exponential', 1.75], // Set the interpolation type
      ['zoom'], // Get current zoom level
      // If the map is at zoom level 12 or below, set circle radius to 2
      12,
      2,
      // If the map is at zoom level 22 or above, set circle radius to 180
      22,
      180
    ]
  }
});

example

Zoom-driven styling example

Change building color based on zoom level

chevron-right

Light-driven styling in Standard

Mapbox Standard uses 3D lighting which affects the entire map, like lighting in the real world. This means that when you switch to dark lights, for example to the “night” preset, your custom layers will also be dark. If you want to change how light affects your custom layer, you will need to configure *-emissive-strength, a property which controls how light is being emitted. *-emissive-strength applies to background, fill, circle, text and line layer types.

Here’s an example how you would set *-emissive-strength for a line layer:

map.addLayer({
  id: 'my-line-layer',
  source: 'vector-source',
  'source-layer': 'road',
  paint: {
    'line-emissive-strength': 1
  }
});

This image illustrates how different line-emissive-strength values are impacting the visual appearance of a line layer:

Was this page helpful?

Set a style​

Choose a style​

Load a style​

Mapbox Standard​

Classic style templates and custom styles​

Configure a style​

Mapbox Standard​

Style imports​

Classic style templates and custom styles​

Work with layers​

Add a layer at runtime​

Update a layer at runtime​

Specify order of a layer at runtime for Mapbox Standard​

Specify order of a layer at runtime for other styles​

Remove a layer at runtime​

Source types​

Vector​

GeoJSON​

Raster​

Raster DEM​

Image​

Layer types​

Fill layer​

Line layer​

Symbol layer​

Circle layer​

Fill extrusion layer​

Hillshade layer​

Heatmap layer​

Raster layer​

Background layer​

Styling your layers​

Work with expressions​

Expression syntax​

Expression types​

Data-driven styling at runtime​

Zoom-driven styling at runtime​

Light-driven styling in Standard​

Set a style

Choose a style

Load a style

Mapbox Standard

Classic style templates and custom styles

Configure a style

Mapbox Standard

Style imports

Classic style templates and custom styles

Work with layers

Add a layer at runtime

Update a layer at runtime

Specify order of a layer at runtime for Mapbox Standard

Specify order of a layer at runtime for other styles

Remove a layer at runtime

Source types

Vector

GeoJSON

Raster

Raster DEM

Image

Layer types

Fill layer

Line layer

Symbol layer

Circle layer

Fill extrusion layer

Hillshade layer

Heatmap layer

Raster layer

Background layer

Styling your layers

Work with expressions

Expression syntax

Expression types

Data-driven styling at runtime

Zoom-driven styling at runtime

Light-driven styling in Standard