A Mapbox style is a document that defines the visual appearance of a map: what data to draw, the order to draw it in, and how to style the data when drawing it. A style document is a JSON object with specific root level and nested properties. This specification defines and describes these properties.
The intended audience of this specification includes:
Root level properties of a Mapbox style specify the map's layers, tile sources and other resources, and default values for the initial camera position when not specified elsewhere.
A style's light property provides global light source for that style.
<% if (ref.$root.light.example) { %>
Sources supply data to be shown on the map. The type of source is specified by the "type" property,
and must be one of <%= source_types.join(', ') %>. Adding a source
won't immediately make data appear on the map because sources don't contain
styling details like color or width. Layers refer
to a source and give it a visual representation. This makes it possible
to style the same source in different ways, like differentiating between
types of roads in a highways layer.
Tiled sources (vector and raster) must specify their details in terms of the TileJSON specification. This can be done in several ways:
"tiles", "minzoom", and
"maxzoom" directly in the source:
"url" to a TileJSON resource:
"{bbox-epsg-3857}"
replacement token to supply the bbox parameter.
(This feature is currently supported only in Mapbox GL JS and Mapbox macOS SDK.)
{% highlight json%}
"wms-imagery": {
"type": "raster",
"tiles": [
'http://a.example.com/wms?bbox={bbox-epsg-3857}&format=image/png&service=WMS&version=1.1.1&request=GetMap&srs=EPSG:3857&width=256&height=256&layers=example'
],
"tileSize": 256
}
{% endhighlight %}
A vector tile source. Tiles must be in Mapbox
Vector Tile format. All geometric coordinates in vector tiles must be between -1 * extent and (extent * 2) - 1 inclusive. 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.
| SDK Support | Mapbox GL JS | iOS SDK | Android SDK |
|---|---|---|---|
| basic functionality | >= 0.10.0 | >= 2.0.0 | >= 2.0.1 |
A raster tile source. For raster tiles hosted by Mapbox, the "url" value should be of the
form mapbox://mapid.
| SDK Support | Mapbox GL JS | iOS SDK | Android SDK |
|---|---|---|---|
| basic functionality | >= 0.10.0 | >= 2.0.0 | >= 2.0.1 |
A GeoJSON source. Data must be provided via a "data"
property, whose value can be a URL or inline GeoJSON.
This example of a GeoJSON source refers to an external GeoJSON document via its URL. The GeoJSON document must be on the same domain or accessible using CORS.
| SDK Requirements | Mapbox GL JS | iOS SDK | Android SDK |
|---|---|---|---|
| basic functionality | >= 0.10.0 | >= 2.0.0 | >= 2.0.1 |
| clustering | >= 0.14.0 | Not yet supported | Not yet supported |
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.
| SDK Support | Mapbox GL JS | iOS SDK | Android SDK |
|---|---|---|---|
| basic functionality | >= 0.10.0 | Not yet supported | Not yet supported |
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.
| SDK Support | Mapbox GL JS | iOS SDK | Android SDK |
|---|---|---|---|
| basic functionality | >= 0.10.0 | Not yet supported | Not yet supported |
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.
<% if (ref.$root.sprite.example) { %>
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 SDKs 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.
<% if (ref.$root.glyphs.example) { %>
A style's transition property provides global transition defaults for that style.
<% if (ref.$root.transition.example) { %>
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 <%= layer_types.join(', ') %>.
Except for layers of the background type, each layer needs to refer to a source. Layers take the data that they get from a source, optionally filter features, and then define how those features are styled.
<% if (ref.$root.layers.example) { %>
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.
Key: supports interpolated functions supports piecewise constant functions transitionable
A Mapbox style contains values of various types, most commonly as values for the style properties of a layer.
Colors are written as JSON strings in a variety of permitted formats: HTML-style hex values, rgb, rgba, hsl, and hsla. Predefined HTML colors names, like yellow and blue, are also permitted.
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 Mapbox styles, 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. Functions allow you to make the appearance of a map feature change with the current zoom level and/or the feature's properties.
| SDK Support | Mapbox GL JS | iOS SDK | Android SDK |
|---|---|---|---|
| basic functionality | >= 0.10.0 | >= 2.0.0 | >= 2.0.1 |
identity type |
>= 0.26.0 | Not yet supported | Not yet supported |
colorSpace |
>= 0.26.0 | Not yet supported | Not yet supported |
Zoom functions allow the appearance of a map feature to change with map’s zoom. Zoom functions can be used to create the illusion of depth and control data density. Each stop is an array with two elements, the first is a zoom and the second is a function output value.
Property functions allow the appearance of a map feature to change with its properties. Property functions can be used to visually differentate 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. Note that support for property functions is not available across all properties and platforms at this time.
Zoom-and-property functions allow the appearance of a map feature to change with both its properties and zoom. Each stop is an array with two elements, the first is an object with a property input value and a zoom, and the second is a function output value. Note that support for property functions is not yet complete.
A filter selects specific features from a layer. A filter is an array of one of the following forms:
["has", key] feature[key] exists
["!has", key] feature[key] does not exist
["==", key, value] equality: feature[key] = value
["!=", key, value] inequality: feature[key] ≠ value
[">", key, value] greater than: feature[key] > value
[">=", key, value] greater than or equal: feature[key] ≥ value
["<", key, value] less than: feature[key] < value
["<=", key, value] less than or equal: feature[key] ≤ value
["in", key, v0, ..., vn] set inclusion: feature[key] ∈ {v0, ..., vn}
["!in", key, v0, ..., vn] set exclusion: feature[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".
Set membership filters are a compact and efficient way to test whether a field matches any of multiple values.
The comparison and set membership filters 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.
This filter requires that the class property of
each feature is equal to either "street_major", "street_minor",
or "street_limited".
The combining filter "all" takes the three other filters that
follow it and requires all of them to be true for a feature
to be included: a feature must have a class equal
to "street_limited", its admin_level must be greater
than or equal to 3, and its type cannot be Polygon. You could
change the combining filter to "any" to allow features matching
any of those criteria to be included - features that are Polygons,
but have a different class value, and so on.
| SDK Support | Mapbox GL JS | iOS SDK | Android SDK |
|---|---|---|---|
| basic functionality | >= 0.10.0 | >= 2.0.0 | >= 2.0.1 |
has/!has |
>= 0.19.0 | >= 3.3.0 | >= 4.1.0 |