Mapbox GL data-driven style reference

Data-driven styles enable a developer to change a map style based on data properties. For example, a developer can change the radius of a circle at an intersection based on the number of pedestrians crossing the intersection, or change the color of a state boundary fill-layer based on the population of each state.

Data-driven style reference guide

To create data-driven styles for a map layer, a developer uses the Mapbox style specification to define how the data relates to the map style.

Required style sheet objects for data-driven styles

Each layer that uses data-driven styles can include the following items in their property functions:

  1. property : The data column name used for the data-driven style. Required
  2. type : One of “identity”, “interval”, “continuous”, or “categorical”. The type object specifies the property-function to use when calculating the data-driven style paint-property ranges.
  3. stops : An array of [value, color] pairs that correspond to the bin ranges to use for the property function. Functions with type: "identity" cannot include the stops property in their definition. Required unless type is “identity.”

Note: Zoom functions and property functions can be combined in the stops property. See zoom and property functions docs.

Property functions

Property functions allow the appearance of a map feature to change with its properties. Property functions can be used to visually differentiate types of features within the same layer or create data visualizations. Each stop is an array with two elements, the first is a property input value and the second is a function output value.

Property-function Description Example
exponential Return the output by interpolating between stops just less than and just greater than the function input. This is the default for continuous value data properties. Style a county fill-color by population, where the color continuously varies from red to blue between 0 and 10 million people.
interval Return the output value of the stop just less than the function input. This is the default for discrete value data properties. Style a county fill-color for average income into 3 color ranges [0-25 red, 25-75 middle, 75+ upper].
categorical Return the output value of the stop equal to the function input Style a circle by the ‘type of restaurant’ data column, which can have values of [‘fastfood’, ‘fastcasual’, or ‘finedining’]
identity Return the input Style transit data routes where color is an attribute in the datasource for each transit line.

Layout and paint functions

Supported data-driven paint and layout properties are documented on the Mapbox Style Specification.

Data-Driven style support is listed in the SDK support table for each paint or layout property.

Examples

Graduated circle map

In a graduated circle map, a layer changes color based on data properties. In this example, the color and radius of the circle layer changes based on the number of pedestrians at that intersection in the data.

Choropleth map

In a choropleth map, a ‘fill’ layer changes color based on data properties. In this example, the color of a state changes based on the population in the data.

Colored line map

In a colored line map, a line layer changes color based on data properties. In this example, the color of a flight path changes based on the difference between local time at the flight’s origin and destination.

3D Building map

In a fill map, extrude buildings in 3D based on data properties. In this example, the extrusion height of the building changes based on the “height” and “min_height” of the building polygon.

Circle layer, circle-color, categorical

In a circle layer, vary the color of the circle based on the category of the ‘ethnicity’ data vale.

"paint": {
    "circle-color": {
        "property": "ethnicity",
        "type": "categorical",
        "stops": [
            ["White", "#fbb03b"],
            ["Black", "#223b53"],
            ["Hispanic", "#e55e5e"],
            ["Asian", "#3bb2d0"],
            ["Other", "#ccc"]
        ]
    }
}

Circle layer, zoom and circle-radius, exponential

In a circle layer, vary the radius of the circle based on the continuous values of the ‘population’ data property.

"paint": {
    "circle-radius": {
        "property": "population",
        "type": "exponential",
        "stops": [
            [{ "zoom": 15, "value": 1 }, 10],
            [{ "zoom": 17, "value": 1 }, 20],
            [{ "zoom": 20, "value": 1 }, 30],
            [{ "zoom": 15, "value": 10 }, 50],
            [{ "zoom": 15, "value": 10 }, 60],
            [{ "zoom": 15, "value": 10 }, 70],
            [{ "zoom": 15, "value": 100 }, 100],
            [{ "zoom": 17, "value": 100 }, 110],
            [{ "zoom": 20, "value": 100 }, 120]
        ]
    },
}

Line layer, line-color, exponential

In a line layer, vary the line-color based on the continuous values of the “time-delta” property.

"paint": {
    "line-color": {
        "property": "time-delta",
        "type": "exponential",
        "stops": [
            [-24, "#ff4e00"],
            [-3, "#eace28"],
            [0, "#ffffff"],
            [3, "#43aaf7"],
            [24, "#1129d3"]
        ]
    }
}

Fill layer, fill-color, interval function

In a fill layer, vary the fill-color and fill-outline-color based on the discrete value of the ‘population’ property.

"paint": {
    "fill-color": {
        "property": "population",
        "type": "interval",
        "stops": [
            [1, "red"],
            [10, "blue"],
            [100, "green"]
        ]
    },
    "fill-outline-color": {
        "property": "population",
        "type": "interval",
        "stops": [
            [1, "red"],
            [10, "blue"],
            [100, "green"]
        ]
    }
}

Fill extrusion layer, extrusion-height, identity function

In a fill-extrusion layer, extrude the the polygon shape from the “min_height” to the “height” property value. Use the exact value in the “height” and “min_height” fields to determine the extrusion height.

"paint": {
    "fill-extrusion-height": {
        "type": "identity",
        "property" : "height"
    },
    "fill-extrusion-base": {
        "property": "min_height",
        "type": "identity"
    }
}

Next Steps

Want to build great visuals using data driven styles? Continue on with the tutorials below:

  1. Graduated Circle Map Tutorial with GL-JS Data-Driven Styles.
  2. Choropleth map tutorial
Additional questions? Ask our support team or learn more about How Mapbox Works.