The Mapbox GL style is an object that defines what data to draw, the order to draw it in, and how to style the data when drawing it. The JSON structure follows the renderer implementation very closely. It provides the basic building blocks out of which more complex styles can be built.
Key: supports interpolated functions supports piecewise constant functions transitionable
Top level properties on the Mapbox GL style object specify the map's appearance, sources, and layers.
Sources supply data to be shown on the map. The type of source is specified by the "type" property,
and must be one of vector, raster, geojson, image, video. Tiled sources (vector and raster) must specify
their details in terms of the TileJSON specification.
This can be done in two ways:
"tiles", "minzoom", and
"maxzoom" directly in the source:
"url" to a TileJSON resource:
A vector tile source. Tiles must be in Mapbox
Vector Tile format. All layers that use a vector source must specify a "source-layer" value.
For vector tiles hosted by Mapbox, the "url" value should be of the
form mapbox://mapid.
A raster tile source. For raster tiles hosted by Mapbox, the "url" value should be of the
form mapbox://mapid.
A GeoJSON source. Data must be provided via a "data"
property, whose value can be a URL or inline GeoJSON.
An image source. The "url" value contains the image location.
The "coordinates" array contains [longitude, latitude] pairs for the image
corners listed in clockwise order: top left, top right, bottom right, bottom left.
A video source. The "urls" value is an array. For each URL in the array,
a video element source will
be created, in order to support same media in multiple formats supported by different browsers.
The "coordinates" array contains [longitude, latitude] pairs for the video
corners listed in clockwise order: top left, top right, bottom right, bottom left.
A style's sprite property supplies a URL template for loading small images to use in
rendering background-pattern, fill-pattern, line-pattern,
and icon-image style properties.
A valid sprite source must supply two types of files:
width and
height properties) and pixel ratio (pixelRatio) of the image and its location within
the sprite (x and y). For example, a sprite containing a single image might have the
following index file contents:
"icon-image": "poi", or with the tokenized value "icon-image": "{icon}" and vector
tile features with a icon property with the value poi.
Mapbox GL renderers will use the value of the sprite property in the style to generate the URLs for
loading both files. First, for both file types, it will append @2x to the URL on high-DPI devices.
Second, it will append a file extension: .json for the index file, and .png for the
image file. For example, if you specified "sprite": "https://example.com/sprite", renderers would
load https://example.com/sprite.json and https://example.com/sprite.png, or
https://example.com/sprite@2x.json and https://example.com/sprite@2x.png.
If you are using Mapbox Studio, you will use prebuilt sprites provided by Mapbox, or you can upload custom SVG images to build your own sprite. In either case, the sprite will be built automatically and supplied by Mapbox APIs. If you want to build a sprite by hand and self-host the files, you can use spritezero-cli, a command line utility that builds Mapbox GL compatible sprite PNGs and index files from a directory of SVGs.
A style's glyphs property provides a URL template for loading signed-distance-field glyph sets in PBF format.
A style's transition property provides global transition defaults for that style.
A style's layers property lists all of the layers available in that style. The type of
layer is specified by the "type" property, and must be one of background, fill, line, symbol, raster, circle.
Layers have two sub-properties that determine how data from that layer is rendered: layout and
paint properties.
Layout properties appear in the layer's "layout" object. They are applied early in the rendering process and
define how data for that layer is passed to the GPU. For efficiency, a layer can share layout properties with
another layer via the "ref" layer property, and should do so where possible. This will decrease
processing time and allow the two layers will share GPU memory and other resources associated with the layer.
Paint properties are applied later in the rendering process. A layer that shares layout properties with another
layer can have independent paint properties. Paint properties appear in the layer's "paint" object.
Layers can also have class-specific paint properties, which are applied only when the map has a certain class
name set. For example, a layer with a "paint.night" property would have those properties applied
when the map has the "night" class set.
Below is a list of types and an explanation of any expression that can be applied to properties in Mapbox GL.
Mapbox GL accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, and hsla. It also supports the predefined HTML colors names, like yellow and blue.
Especially of note is the support for hsl, which can be easier to reason about than rgb().
One of a fixed list of string values. Use quotes around values.
{% highlight json %} { "text-transform": "uppercase" } {% endhighlight %}A string is basically just text. In the case of Mapbox GL, you're going to put it in quotes. Strings can be anything, though pay attention to the case of text-field - it actually will refer to features, which you refer to by putting them in curly braces, as seen in the example below.
Boolean means yes or no, so it accepts the values true or false.
A number value, often an integer or floating point (decimal number). Written without quotes.
{% highlight json %} { "text-size": 24 } {% endhighlight %}Arrays are comma-separated lists of one or more numbers in a specific order. For example, they're used in line dash arrays, in which the numbers specify intervals of line, break, and line again.
{% highlight json %} { "line-dasharray": [2, 4] } {% endhighlight %}The value for any layout or paint property may be specified as a function, allowing you to parameterize the value according to the current zoom level. Functions are written as an array of stops, where each stop is an array with two elements: a zoom level and a corresponding value. Stops must be in ascending zoom order.
Some properties support interpolated functions. The result of an interpolated function is an
interpolated value between the last stop whose zoom level is less than or equal to the current zoom level,
and the next stop. By default, linear interpolation is used, but you can use a different exponential base
for the interpolation curve via the base property. If the current zoom is less than the first
stop or greater than the last stop, the result is the value from the first or last stop respectively.
All other properties support piecewise constant functions. The result of a piecewise constant function is the value of the last stop whose zoom value is less than or equal to the current zoom level.
A filter selects specific features from a layer. A filter is an array of one of the following forms:
["==", key, value] equality: key = value
["!=", key, value] inequality: key ≠ value
[">", key, value] greater than: key > value
[">=", key, value] greater than or equal: key ≥ value
["<", key, value] less than: key < value
["<=", key, value] less than or equal: key ≤ value
["in", key, v0, ..., vn] set inclusion: key ∈ {v0, ..., vn}
["!in", key, v0, ..., vn] set exclusion: key ∉ {v0, ..., vn}
["all", f0, ..., fn] logical AND: f0 ∧ ... ∧ fn
["any", f0, ..., fn] logical OR: f0 ∨ ... ∨ fn
["none", f0, ..., fn] logical NOR: ¬f0 ∧ ... ∧ ¬fn
A filter's key must be a string that identifies a feature property, or
the special key "$type", which identifies the feature type. A value
(and v0, ..., vn for set operators) must be a string,
number, or boolean to compare the property value
against. For the "$type" key it must be one of "Point",
"LineString", or "Polygon".
The binary and set operators implement strictly-typed comparisons; for example, all of the
following evaluate to false: 0 < "1", 2 == "2", "true" in [true, false].
The "all", "any", and "none" filter operators are
used to create compound filters. The values f0, ..., fn must be
filter expressions themselves.