Sorry, you need to enable JavaScript to visit this website.

Map Style Specification

 

Last edit: 2019.12.13

On this page

Purpose

Map style is written in JSON format. It specifies how to:

  • Style the symbols, lines, polygons, background, hills' shades, heatmap points, raster tiles, circles, and extruded polygons.
  • Which of them should be drawn.
  • The order in which to draw them.

Root Properties

Root level properties define default values, tile sources, and the map's layers.

Properties
Name Required Default Value Description
name
string
no none Name of the style.
version
number
yes none Version of the style specification.
Value: 8.
zoom
number
no none Default zoom level. Only applies if the map has not been positioned by any other means (e.g., user interaction).
bearing
number
(degrees)
no 0 Default bearing. For instance, 90o sets east as the up direction. Only applies if the map has not been positioned by any other means (e.g., user interaction).
center
array of numbers
no none Default map center. The array shall consist of two values: longitude and latitude. They can be either integer or floating point numbers. Only applies if the map has not been positioned by any other means (e.g., user interaction).
pitch
number
(degrees)
no 0 Default pitch. The view is straight down at the map when the value is 0. Greater values set the view towards the horizon. Only applies if the map has not be positioned by any other means (e.g., user interaction).
sources
object
yes none Data source. Properties of the source object can be found at source properties.
light
object
no none Light source. Properties of the light object can be found at light properties.
glyphs
object
no /
yes (if any layer uses text-field property)
none The URL must contain the scheme, authority, path, and the {fontstack} and {range} tokens. The property will be used to load glyphs in PBF format.
transition
object
no none Defines the default transition to use across the style. Properties of the transition object can be found at transition properties.
layers
array of objects
yes none The array of layers. Layers will be drawn in the same order as they appear in this property.
sprite
string
no /
yes (if any layer uses any of the following properties: icon-image, line-pattern, fill-extrusion-pattern, background-pattern, fill-pattern)
none The URL must contain a scheme, authority, and path. The property is used to load the sprite image. The file extension for the sprite image (.png) and metadata (.json) will be added automatically.

▲ Return to top

Source Properties

A source provides data that is displayed on the map.

  • The source object needs to have a property named type.
  • There are several types of source: vector, raster, raster-dem (Web SDK only), geojson, image, video (Web SDK Only).
  • Each of them have different properties which are described below.
Vector Properties
Name Required Default Value Description
url
string
no none URL to a resource.
tiles
array of strings
no none An array of the URLs to a resource. This property can contain one or more URLs.
attribution
string
no none Attribution that is shown when the map is displayed.
scheme
string
no xyz Scheme of the data.
bounds
array of numbers
no [-180, -85.051129, 180, 85.051129] An array of the longitude and latitude pairs containing southwest and northeast corners. No tiles will be requested outside of those bounds.
minzoom
number
no 0 Minimum zoom level the tiles are available for.
maxzoom
number
no 22 Maximum zoom level the tiles are available for.
Raster Properties
Name Required Default Value Description
url
string
no none URL to a resource.
tiles
array of strings
no none An array of the URLs to a resource. This property can contain one or more URLs.
attribution
string
no none Attribution that is shown when the map is displayed.
scheme
string
no xyz Scheme of the data.
Values:
  • xyz (Slippy map tilenames)
  • tms (OSGeo spec)
bounds
array of numbers
no [-180, -85.051129, 180, 85.051129] An array of the longitude and latitude pairs containing southwest and northeast corners. No tiles will be requested outside of those bounds.
minzoom
number
no 0 Minimum zoom level the tiles are available for.
maxzoom
number
no 22 Maximum zoom level the tiles are available for.
tileSize
number
(pixels)
no 512 Minimum size to display tiles.
Raster-Dem Properties
Name Required Default Value Description
url
string
no none URL to a resource.
tiles
array of strings
no none An array of the URLs to a resource. This property can contain one or more URLs.
attribution
string
no none Attribution that is shown when the map is displayed.
encoding
string
no mapbox Encoding used by source.
Values:
  • mapbox (Mapbox Terrain RGB tiles)
  • terrarium (Terrarium format PNG tiles)
bounds
array of numbers
no [-180, -85.051129, 180, 85.051129] An array of the longitude and latitude pairs containing southwest and northeast corners. No tiles will be requested outside of those bounds.
minzoom
number
no 0 Minimum zoom level the tiles are available for.
maxzoom
number
no 22 Maximum zoom level the tiles are available for.
tileSize
number
(pixels)
no 512 Minimum size to display tiles.
GeoJSON Properties
Name Required Default Value Description
data
string
yes none URL to a GeoJSON resource or inline GeoJSON.
buffer
number
no 128 Size of the tile buffer.
  • The number must be between 0 and 512 inclusive.
  • 0 means no buffer.
  • Larger values result in slower performance and fewer rendering artifacts.
attribution
string
no none Attribution that is shown when the map is displayed.
tolerance
number
no 0.375 Tolerance of Douglas-Peucker simplification. Lower values result in more detailed geometries and slower performance.
cluster
boolean
no false If true and the data is a collection of point features, the features are grouped into clusters by clusterRadius. Groups are new point features with extra properties:
  • cluster (Boolean value, the point is a cluster)
  • cluster_id (Integer value, a unique cluster's id)
  • point_count (Integer value, the number of points grouped into this cluster)
  • point_count_abbreviated (Integer value, the number of an abbreviated point count)
clusterRadius
number
no 50 Radius to group points into clusters. Number must be equal to or greater than 0.
clusterMaxZoom
number
no maxzoom-1 Maximum zoom level to group points into clusters.
clusterProperties
object
no none Allows the definition of custom properties for generated clusters, combining values from clustered points.
Syntax: {propertyName: [operator, pointExpression]}
  • propertyName: string which contains custom property name.
  • operator: any expression which has at least 2 arguments.
  • pointExpression: any expression which returns result for a single point.
maxzoom
number
no 18 Maximum zoom level to create the tiles.
lineMetrics
boolean
no false true if line distance metrics should be calculated. Needs to be true for line layers which have line-gradient values specified.
generateId
boolean
no false true if ids should be generated for GeoJSON features. The feature.id property will be created if it does not exist. The property will be assigned a value based on its index in the features array and will overwrite any existing value.
Image Properties
Name Required Default Value Description
url
string
yes none URL to an image resource.
coordinates
array of arrays of numbers
yes none Corners of an image specified in [longitude, latitude] pairs. Arrays containing coordinates are listed in clockwise order:
  1. top-left
  2. top-right
  3. bottom-right
  4. bottom-left
Video Properties
Name Required Default Value Description
urls
array of strings
yes none URLs to video resources.
coordinates
array of arrays of numbers
yes none Corners of a video specified in [longitude, latitude] pairs. Arrays containing coordinates are listed in clockwise order:
  1. top-left
  2. top-right
  3. bottom-right
  4. bottom-left
SDK Support
Source Type Web SDK Mobile SDK
vector
raster
raster-dem
geojson
image
video

▲ Return to top

Sprite Property

The sprite property provides the URL to load images used in the rendering process. Properties which use sprite are:

  • icon-image
  • fill-extrusion-pattern
  • line-pattern
  • fill-pattern
  • background-pattern

A sprite source must contain index and image files.

Index file

The index file must be written in JSON format and contain a JSON object. The keys of the root object are identifiers to be used in style properties.

{
      "145": {
        "width": 24,
        "height": 24,
        "x": 697,
        "y": 600,
        "pixelRatio": 1
      }
    }
Name Description
width
number
Width of the image.
height
number
Height of the image.
x
number
Horizontal location of the image.
y
number
Vertical location of the image.
pixelRatio
array of numbers
Pixel ratio of the image.

Sprite file

The sprite file contains PNG images.

▲ Return to top

Glyphs Property

The URL template is used to load glyphs in PBF format.

Example

http://localhost:6001/glyphs/{fontstack}/{range}.pbf
Token Name Description
{fontstack} The token is replaced with requested glyphs from the text-font layout property.
{range} The token is replaced with Unicode code points. Ranges are calculated at runtime.

▲ Return to top

Transition Properties

Defines timing for the interpolation between the style's property values. It can be set globally for the style, but also configured per layer.

Properties
Name Required Default Value Description
duration
number
(milliseconds)
no 300 Time needed to complete transitions. Value needs to be equal to or greater than 0.
delay
number
(milliseconds)
no 0 Time before a transition starts.
SDK Support
Property Name Web SDK Mobile SDK
duration
delay

▲ Return to top

Light Properties

Defines the light source for the style.

Properties
Name Required Default Value Description
anchor
string
no viewport Anchor of the source light.
Values:
  • viewport: The light source is aligned to the viewport.
  • map: The light source is aligned to the map.
intensity
number
no 0.5 Intensity of the lighting. Value must be between 0 and 1 inclusive. The higher the value, the higher the contrast.
color
color
no #ffffff Color of the light source for extruded geometries.
position
array of numbers
no [1.15, 210, 30] Position of the light source which is relative to extruded geometries.
  • First element determines the distance between the light and the base of an object.
  • Second element determines position of the light source relative to its anchor.
  • Third element determines the height of the light source given in degrees.
    • The value must be between 0o and 180o, while 0o means directly above and 180o directly below.
SDK Support
Property Name Web SDK Mobile SDK
anchor
intensity
color
position

▲ Return to top

Layer Properties

Layer defines how specific features retrieved from a source are rendered on the map. The renderer decides how to draw a feature based on its properties and the style of the layer that describes it. Only the background type layer does not need a source property.

Properties
Name Required Default Value Description
id
string
yes none ID of the layer. Must be unique.
type
string
yes none Type of the layer.
Values:
  • fill
  • symbol
  • circle
  • raster
  • background
  • line
  • heatmap
  • fill-extrusion
  • hillshade
metadata
object
no none Attributes that do not affect rendering.
source
string
no / yes (if type is not equal to background) none Name of a source to be used.
source-layer
string
no / yes (if source is equal to vector) none A layer to use from vector source.
minzoom
number
no none The minimum zoom level to draw the layer. Number must be between 0 and 22 inclusive.
maxzoom
number
no none The maximum zoom level to draw the layer. Number must be between 0 and 22 inclusive.
filter
array
(filter)
no none If the feature does not match the condition, then it is not drawn on the map.
layout
object
no none Layout properties. Properties of the layout object can be found at layout properties.
paint
object
no none Paint properties. Properties of the paint object can be found at paint properties.

▲ Return to top

Layout Properties

Background Properties
Name Required Default Value Description
visibility
string
no visible Visibility of the layer.
Values:
  • visible: Layer is visible.
  • none: Layer is hidden.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
visibility ✔ / ✖ ✔ / ✖
Fill Properties
Name Required Default Value Description
visibility
string
no visible Visibility of the layer.
Values:
  • visible: Layer is visible.
  • none: Layer is hidden.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
visibility ✔ / ✖ ✔ / ✖
Line Properties
Name Required Default Value Description
visibility
string
no visible Visibility of the layer.
Values:
  • visible: Layer is visible.
  • none: Layer is hidden.
line-cap
string
no butt Type of the line's endings.
Values:
  • butt: Squared-off end drawn to the endpoint of the line.
  • round: Rounded end drawn beyond the endpoint of the line with a radius of half of the line's width and centered on the endpoint of the line.
  • square: Squared-off end drawn beyond the endpoint of the line at a distance of half of the line's width.
line-join
string
no miter Type of the line's join.
Values:
  • bevel: Squared-off end join drawn beyond the endpoint of the line at a distance of half of the line's width.
  • round: Rounded end join drawn beyond the endpoint of the line at a radius of half of the line's width and centered on the endpoint of the line.
  • miter: Sharp, angled corner join drawn with the outer sides beyond the endpoint of the path until they meet.
line-miter-limit
number
no 2 Used to convert miter joins to bevel ones for sharp angles.
line-round-limit
number
no 1.05 Used to convert round joins to miter ones for shallow angles.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
visibility ✔ / ✖ ✔ / ✖
line-cap ✔ / ✖ ✔ / ✖
line-join ✔ / ✔ ✔ / ✔
line-miter-limit ✔ / ✖ ✔ / ✖
line-round-limit ✔ / ✖ ✔ / ✖
Symbol Properties
Name Required Default Value Description
visibility
string
no visible Visibility of the layer.
Values:
  • visible: Layer is visible.
  • none: Layer is hidden.
symbol-sort-key
number
no none Used to sort features. Features are drawn in ascending order.
symbol-z-order
string
no auto Type of sorting features. Affects the order of overlapping features within the same layer are being rendered.
Values:
  • auto: Sorting features is based on the symbol-sort-key property. If it is not set, then features are sorted by their vertical position relative to the viewport.
  • viewport-y: Features are sorted by their vertical position relative to the viewport.
  • source: No sorting is enabled. They are drawn in the same order as they appear in the source data.
symbol-placement
string
no point Placement of the label.
Values:
  • point: Places a label at its geometry.
  • line: Places a label along the line of the geometry.
  • line-center: Places a label at the center of the line of the geometry.
symbol-spacing
number
(pixels)
no 250 Distance between symbol anchors. symbol-placement needs to be line. Number must be greater than 0.
symbol-avoid-edges
boolean
no false The symbol will not be drawn when it crosses tile edge if this property is set to true.
icon-allow-overlap
boolean
no false The icon will be drawn even if a collision is detected with other already drawn icons. icon-image needs to be set.
icon-ignore-placement
boolean
no false Other symbols will be visible even if a collision is detected with the icon. icon-image needs to be set.
icon-optional
boolean
no false Only text will be drawn if the icon collides with other symbols.
icon-rotation-alignment
string
no auto Sets icon rotation alignment. text-field and icon-image both need to be set.
Values:
  • map: Aligns the icon east-west if symbol-placement is set to point. In case symbol-placement is set to line, it aligns the icon horizontal with the line.
  • viewport: The icon is aligned horizontally with the viewport.
  • auto: If symbol-placement is set to point, then the alignment is the same as viewport. Otherwise, alignment is set to map.
icon-size
number
no 1 Scales the icon image size by multiplying its original size by this property. icon-image needs to be set. The number must be greater than or equal to 0.
icon-text-fit
string
no none Scales the icon to fit the text.
Values:
  • none: The icon is not scaled.
  • width: The icon is scaled horizontally.
  • height: The icon is scaled vertically.
  • both: The icon is scaled both horizontally and vertically.
icon-text-fit-padding
array of numbers
no [0, 0, 0, 0] Padding around the area defined by icon-text-fit in clockwise order starting from the top.
  • icon-image and text-field both need to be set.
  • icon-text-fit needs to be set to any value but none.
icon-image
string
no none Name of an image in the sprite config file.
icon-rotate
number
(degrees)
no 0 Icon is rotated clockwise by this property. icon-image needs to be set.
icon-padding
number
(pixels)
no 2 Extra area surrounding an icon to detect collisions with other symbols. icon-image needs to be set.
icon-keep-upright
boolean
no false Prevents an icon from being rendered upside-down.
  • icon-image needs to be set.
  • icon-rotation-alignment needs to be set to line.
icon-offset
array of numbers
(pixels)
no [0, 0] An icon's distance from its anchor. Each element of the array is multiplied by the value of icon-size.
  • Positive values place the icon right and down.
  • Negative values place it left and up.
  • icon-image needs to be set.
icon-anchor
string
no center Sets which part of the icon is closest to the anchor. icon-image needs to be set.
Values:
  • center: The center of the icon is the closest to the anchor.
  • left: The left side of the icon is the closest to the anchor.
  • right: The right side of the icon is the closest to the anchor.
  • top: The top of the icon is the closest to the anchor.
  • top-left: The top left corner of the icon is the closest to the anchor.
  • top-right: The top right corner of the icon is the closest to the anchor.
  • bottom-left: The bottom left corner of the icon is the closest to the anchor.
  • bottom-right: The bottom right corner of the icon is the closest to the anchor.
icon-pitch-alignment
string
no auto Orientation of the icon when a map is pitched. icon-image needs to be set.
Values:
  • viewport: The orientation of the icon is aligned to the plane of the viewport.
  • map: The orientation of the icon is aligned to the plane of the map.
  • auto: The orientation of the icon is based on icon-rotation-alignment.
text-pitch-alignment
string
no auto Orientation of the text when a map is pitched. text-field needs to be set.
Values:
  • viewport: The orientation of the text is aligned to the plane of the viewport.
  • map: The orientation of the text is aligned to the plane of the map.
  • auto: The orientation of the text is based on text-rotation-alignment.
text-rotation-alignment
string
no auto Sets text rotation alignment. text-field needs to be set.
Values:
  • viewport: The text is aligned horizontal with the viewport.
  • map: Aligns the text east-west if symbol-placement is set to point. In case symbol-placement is set to line, it aligns the icon horizontal with the line.
  • auto: If symbol-placement is set to point, then the alignment is the same as viewport. Otherwise, alignment is set to map.
text-field
string
no none Text to be displayed as a symbol label.
text-font
array of strings
no ["Open Sans Regular", "Arial Unicode MS Regular"] Font to be used to display text. text-field needs to be set.
text-size
number
(pixels)
no 16 Text size. text-field needs to be set.
text-max-width
number
(ems)
no 10 Maximum width of the text. text-field needs to be set.
text-line-height
number
(ems)
no 1.2 Text leading value for multi-line text. text-field needs to be set.
text-letter-spacing
number
(ems)
no 0 Sets spacing between letters. text-field needs to be set.
text-justify
string
no center Justifies the text. text-field needs to be set.
Values:
  • auto: The text is justified to the anchor position.
  • left: The text is justified to the left.
  • right: The text is justified to the right.
  • center: The text is centered.
text-radial-offset
number
(ems)
no 0 Radial offset of the text in the direction of the symbol's anchor. text-field needs to be set.
text-variable-anchor
array of strings
no none Sets the position of the text. The render will try to place the label using the values provided in the array. text-field needs to be set. symbol-placement needs to be set to point.
Values:
  • center: The center of the text is the closest to the anchor.
  • left: The left side of the text is the closest to the anchor.
  • right: The right side of the text is the closest to the anchor.
  • top: The top of the text is the closest to the anchor.
  • bottom: The bottom of the text is the closest to the anchor.
  • top-left: The top-left corner of the text is the closest to the anchor.
  • top-right: The top-right corner of the text is the closest to the anchor.
  • bottom-left: The bottom-left corner of the text is the closest to the anchor.
  • bottom-right: The bottom-right corner of the text is the closest to the anchor.
text-anchor
string
no center Sets the position of the text. The render will try to place the label using the values provided in the array. text-field needs to be set. It has no effect if text-variable-anchor is set.
Values:
  • center: The center of the text is the closest to the anchor.
  • left: The left side of the text is the closest to the anchor.
  • right: The right side of the text is the closest to the anchor.
  • top: The top of the text is the closest to the anchor.
  • bottom: The bottom of the text is the closest to the anchor.
  • top-left: The top left corner of the text is the closest to the anchor.
  • top-right: The top right corner of the text is the closest to the anchor.
  • bottom-left: The bottom left corner of the text is the closest to the anchor.
  • bottom-right: The bottom right corner of the text is the closest to the anchor.
text-max-angle
number
(degrees)
no 45 Maximum angle change between adjacent characters. text-field needs to be set and symbol-placement needs to be set to line or line-center.
text-rotate
number
(degrees)
no 0 Rotates the text clockwise. text-field needs to be set.
text-padding
number
(pixels)
no 2 Extra area surrounding text for detecting collisions with other symbols. text-field needs to be set. Number has to be greater than or equal to 0.
text-keep-upright
boolean
no true Prevents text from being rendered upside-down. text-field needs to be set, text-rotation-alignment needs to be set to map and symbol-placement needs to be set to line or line-center.
text-transform
string
no none Capitalizes text. text-field needs to be set.
Values:
  • none: The text is displayed as it is.
  • uppercase: The text is displayed in uppercase.
  • lowercase: The text is displayed in lowercase.
text-offset
array of numbers
(ems)
no [0, 0] Text distance from its anchor.
  • Positive values place the icon right and down.
  • Negative values place it left and up.
  • text-field needs to be set.
text-allow-overlap
boolean
no false The text will be drawn even if a collision is detected with other already drawn icons. text-field needs to be set.
text-ignore-placement
boolean
no false Other symbols will be visible even if a collision is detected with the text. text-field needs to be set.
text-ignore-placement
boolean
no false Only an icon will be drawn if the text collides with other symbols. text-field and icon-image both need to be set.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
visibility ✔ / ✖ ✔ / ✖
symbol-sort-key ✔ / ✔ ✔ / ✔
symbol-z-order ✔ / ✖ ✔ / ✖
symbol-placement ✔ / ✖ ✔ / ✖
symbol-spacing ✔ / ✖ ✔ / ✖
symbol-avoid-edges ✔ / ✖ ✔ / ✖
icon-allow-overlap ✔ / ✖ ✔ / ✖
icon-ignore-placement ✔ / ✖ ✔ / ✖
icon-optional ✔ / ✖ ✔ / ✖
icon-rotation-alignment ✔ / ✖ ✔ / ✖
icon-size ✔ / ✔ ✔ / ✔
icon-text-fit ✔ / ✖ ✔ / ✖
icon-text-fit-padding ✔ / ✖ ✔ / ✖
icon-image ✔ / ✔ ✔ / ✔
icon-rotate ✔ / ✔ ✔ / ✔
icon-padding ✔ / ✖ ✔ / ✖
icon-keep-upright ✔ / ✖ ✔ / ✖
icon-offset ✔ / ✔ ✔ / ✔
icon-anchor ✔ / ✔ ✔ / ✔
icon-pitch-alignment ✔ / ✖ ✔ / ✖
text-pitch-alignment ✔ / ✖ ✔ / ✖
text-rotation-alignment ✔ / ✖ ✔ / ✖
text-field ✔ / ✔ ✔ / ✔
text-font ✔ / ✔ ✔ / ✔
text-size ✔ / ✔ ✔ / ✔
text-max-width ✔ / ✔ ✔ / ✔
text-line-height ✔ / ✖ ✔ / ✖
text-letter-spacing ✔ / ✔ ✔ / ✔
text-justify ✔ / ✔ ✔ / ✔
text-radial-offset ✔ / ✔ ✔ / ✔
text-variable-anchor ✔ / ✖ ✔ / ✖
text-anchor ✔ / ✔ ✔ / ✔
text-max-angle ✔ / ✖ ✔ / ✖
text-rotate ✔ / ✔ ✔ / ✔
text-padding ✔ / ✖ ✔ / ✖
text-keep-upright ✔ / ✖ ✔ / ✖
text-transform ✔ / ✔ ✔ / ✔
text-offset ✔ / ✔ ✔ / ✔
text-allow-overlap ✔ / ✖ ✔ / ✖
text-ignore-placement ✔ / ✖ ✔ / ✖
text-optional ✔ / ✖ ✔ / ✖
Raster Properties
Name Required Default Value Description
visibility
string
no visible Visibility of the layer.
Values:
  • visible: Layer is visible.
  • none: Layer is hidden.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
visibility ✔ / ✖ ✔ / ✖
Circle Properties
Name Required Default Value Description
visibility
string
no visible Visibility of the layer.
Values:
  • visible: Layer is visible.
  • none: Layer is hidden.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
visibility ✔ / ✖ ✔ / ✖
Fill-Extrusion Properties
Name Required Default Value Description
visibility
string
no visible Visibility of the layer.
Values:
  • visible: Layer is visible.
  • none: Layer is hidden.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
visibility ✔ / ✖ ✔ / ✖
Heatmap Properties
Name Required Default Value Description
visibility
string
no visible Visibility of the layer.
Values:
  • visible: Layer is visible.
  • none: Layer is hidden.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
visibility ✔ / ✖ ✔ / ✖
Hillshade Properties
Name Required Default Value Description
visibility
string
no visible Visibility of the layer.
Values:
  • visible: Layer is visible.
  • none: Layer is hidden.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
visibility ✔ / ✖ ✔ / ✖

▲ Return to top

Paint Properties

Background Properties
Name Required Default Value Description
background-color
color
no #000000 Background's color. It has no effect if background-pattern is set.
background-pattern
string
no none Name of a sprite image to use.
background-opacity
number
no 1 Opacity of the background. Number must be between 0 and 1 inclusive.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
background-color ✔ / ✖ ✔ / ✖
background-pattern ✔ / ✖ ✔ / ✖
background-opacity ✔ / ✖ ✔ / ✖
Fill Properties
Name Required Default Value Description
fill-antialias
boolean
no true If true, the layer should be antialiased.
fill-opacity
number
no 1 Opacity of the fill. Number must be between 0 and 1 inclusive.
fill-color
color
no #000000 Fill's color. It has no effect if fill-pattern is set.
fill-outline-color
string
no none The outline color of the fill.
  • If not set, it has the same value as fill-color.
  • It has no effect if fill-pattern is set.
  • fill-antialias needs to be true.
fill-translate
array of numbers
(pixels)
no [0, 0] The geometry's offset.
  • Positive values indicate right and down
  • Negative values indicate left and up.
fill-translate-anchor
string
no map Defines what fill-translate is relative to. fill-translate needs to be set.
Values:
  • viewport: The translation is relative to the viewport.
  • map: The translation is relative to the map.
fill-pattern
string
no none Name of a sprite image to use as a fill.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
fill-antialias ✔ / ✖ ✔ / ✖
fill-opacity ✔ / ✔ ✔ / ✔
fill-color ✔ / ✔ ✔ / ✔
fill-outline-color ✔ / ✔ ✔ / ✔
fill-translate ✔ / ✖ ✔ / ✖
fill-translate-anchor ✔ / ✖ ✔ / ✖
fill-pattern ✔ / ✔ ✔ / ✔
Line Properties
Name Required Default Value Description
line-opacity
number
no 1 Opacity of the line. Number must be between 0 and 1 inclusive.
line-color
color
no #000000 Line's color. It has no effect if line-pattern is set.
line-translate
array of numbers
(pixels)
no [0, 0] The geometry's offset.
  • Positive values indicate right and down.
  • Negative values indicate left and up.
line-translate-anchor
string
no map Defines what line-translate is relative to. line-translate needs to be set.
Values:
  • viewport: The translation is relative to the viewport.
  • map: The translation is relative to the map.
line-pattern
string
no none Name of a sprite image to draw the line.
line-width
number
(pixels)
no 1 Line's thickness. Number must be greater than or equal to 0.
line-gap-width
number
(pixels)
no 0 Width of the inner gap.
line-offset
number
(pixels)
no 0 The line's offset.
  • A positive value places a line to the right.
  • A negative value places a line to the left.
line-blur
number
(pixels)
no 0 Blur applied to the line.
line-dasharray
array of numbers
(line widths)
no none Defines lengths of the dashes and gaps. The lengths are scaled by the line-width.
line-gradient
string
no none Defines a gradient to color the line.
  • It has no effect if line-pattern or line-dasharray is set.
  • The source needs to be geojson.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
line-opacity ✔ / ✔ ✔ / ✔
line-color ✔ / ✔ ✔ / ✔
line-translate ✔ / ✖ ✔ / ✖
line-translate-anchor ✔ / ✖ ✔ / ✖
line-width ✔ / ✔ ✔ / ✔
line-gap-width ✔ / ✔ ✔ / ✔
line-offset ✔ / ✔ ✔ / ✔
line-blur ✔ / ✔ ✔ / ✔
line-dasharray ✔ / ✖ ✔ / ✖
line-pattern ✔ / ✔ ✔ / ✔
line-gradient ✔ / ✖ ✔ / ✖
Symbol Properties
Name Required Default Value Description
icon-opacity
number
no 1 Opacity of the icon.
  • icon-image needs to be set.
  • The number must be between 0 and 1 inclusive.
icon-color
color
no #000000 Icon's color. icon-image needs to be set.
icon-translate
array of numbers
(pixels)
no [0, 0] An icon's anchor is moved from its original placement.
  • Positive values place the icon right and down.
  • Negative values place the icon left and up.
  • icon-image needs to be set.
icon-translate-anchor
string
no map Defines what icon-translate is relative to. icon-translate and icon-image both need to be set.
Values:
  • viewport: The translation is relative to the viewport.
  • map: The translation is relative to the map.
icon-halo-color
color
no rgba(0, 0, 0, 0) Icon's halo color. icon-image needs to be set.
icon-halo-width
number
(pixels)
no 0 Icon's halo width. icon-image needs to be set.
icon-halo-blur
number
(pixels)
no 0 Fades out the halo.
  • Number must be equal to or greater than 0.
  • icon-image needs to be set.
text-opacity
number
no 1 Opacity of the text.
  • text-field needs to be set.
  • Number must be between 0 and 1 inclusive.
text-color
color
no #000000 Text's color. text-field needs to be set.
text-halo-color
color
no rgba(0, 0, 0, 0) Text's halo color. text-field needs to be set.
text-halo-width
number
(pixels)
no 0 Text's halo width.
  • text-field needs to be set.
  • Number must be equal to or greater than 0.
text-halo-blur
number
(pixels)
no none Text's halo blur.
  • text-field needs to be set.
  • Number must be equal to or greater than 0.
text-translate
array of numbers
(pixels)
no [0, 0] The text's anchor is moved from its original placement.
  • Positive values place the icon right and down.
  • Negative values place the icon left and up.
  • The text-field needs to be set.
text-translate-anchor
string
no map Defines what text-translate is relative to. text-translate and text-field both need to be set.
Values:
  • viewport: The translation is relative to the viewport.
  • map: The translation is relative to the map.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
icon-opacity ✔ / ✔ ✔ / ✔
icon-color ✔ / ✔ ✔ / ✔
icon-halo-color ✔ / ✔ ✔ / ✔
icon-halo-width ✔ / ✔ ✔ / ✔
icon-halo-blur ✔ / ✔ ✔ / ✔
icon-translate ✔ / ✖ ✔ / ✖
icon-translate-anchor ✔ / ✖ ✔ / ✖
text-opacity ✔ / ✔ ✔ / ✔
text-color ✔ / ✔ ✔ / ✔
text-halo-color ✔ / ✔ ✔ / ✔
text-halo-width ✔ / ✔ ✔ / ✔
text-halo-blur ✔ / ✔ ✔ / ✔
text-translate ✔ / ✖ ✔ / ✖
text-translate-anchor ✔ / ✖ ✔ / ✖
Raster Properties
Name Required Default Value Description
raster-opacity
number
no 1 Opacity of the image. Number must be between 0 and 1 inclusive.
raster-hue-rotate
number
(degrees)
no 0 Rotates hues around the color wheel.
raster-birghtness-min
number
no 0 Minimum brightness of the image. Number must be between 0 and 1 inclusive.
raster-birghtness-max
number
no 1 Maximum brightness of the image. Number must be between 0 and 1 inclusive.
raster-saturation
number
no 0 Sets saturation of the image. Number must be between -1 and 1 inclusive.
raster-contrast
number
no 0 Sets contrast of the image. Number must be between -1 and 1 inclusive.
raster-resampling
string
no linear Type of the image resampling.
Values:
  • linear: Interpolates pixel values by weighted average of the four closest pixels creating a smooth and blurry look when overscaled.
  • nearest: Interpolates pixel values by the nearest pixel creating a sharp and pixelated look when overscaled.
raster-fade-duration
number
(milliseconds)
no 300 Fade in duration of a tile.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
raster-opacity ✔ / ✖ ✔ / ✖
raster-hue-rotate ✔ / ✖ ✔ / ✖
raster-brightness-min ✔ / ✖ ✔ / ✖
raster-brightness-max ✔ / ✖ ✔ / ✖
raster-saturation ✔ / ✖ ✔ / ✖
raster-contrast ✔ / ✖ ✔ / ✖
raster-resampling ✔ / ✖ ✔ / ✖
raster-fade-duration ✔ / ✖ ✔ / ✖
Circle Properties
Name Required Default Value Description
circle-opacity
number
no 1 Opacity of the circle. Number must be between 0 and 1 inclusive.
circle-color
color
no #000000 Color of the circle.
circle-translate
array of numbers
(pixels)
no [0, 0] The geometry's offset.
  • Positive values indicate right and down.
  • Negative values indicate left and up.
circle-translate-anchor
string
no map Defines what circle-translate is relative to. circle-translate needs to be set.
Values:
  • viewport: The translation is relative to the viewport.
  • map: The translation is relative to the map.
circle-radius
number
(pixels)
no 5 Radius of the circle. Number must be equal to or greater than 0.
circle-blur
number
no 0 Only the center point of the circle is not blurred when the value of this property is equal to 1.
circle-pitch-scale
string
no map Scaling type when map is pitched.
Values:
  • viewport: Circles are not scaled.
  • map: Circles are scaled by their distance to the camera.
circle-pitch-alignment
string
no viewport Orientation of the circle when map is pitched.
Values:
  • viewport: The orientation of the circle is aligned to the plane of the viewport.
  • map: The orientation of the circle is aligned to the plane of the map.
circle-stroke-width
number
(pixels)
no 0 Width of the circle's stroke. Number must be equal to or greater than 0.
circle-stroke-color
color
no #000000 Color of the circle's stroke.
circle-stroke-opacity
number
no 1 Opacity of the circle's stroke. Number must be between 0 and 1 inclusive.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
circle-radius ✔ / ✔ ✔ / ✔
circle-color ✔ / ✔ ✔ / ✔
circle-blur ✔ / ✔ ✔ / ✔
circle-opacity ✔ / ✔ ✔ / ✔
circle-translate ✔ / ✖ ✔ / ✖
circle-translate-anchor ✔ / ✖ ✔ / ✖
circle-pitch-scale ✔ / ✖ ✔ / ✖
circle-pitch-alignment ✔ / ✖ ✔ / ✖
circle-stroke-width ✔ / ✔ ✔ / ✔
circle-stroke-color ✔ / ✔ ✔ / ✔
circle-stroke-width ✔ / ✔ ✔ / ✔
Fill-Extrusion Properties
Name Required Default Value Description
fill-extrusion-opacity
number
no 1 Opacity of the fill extrusion layer. Number must be between 0 and 1 inclusive.
fill-extrusion-color
color
no #000000 Color of the extruded fill.
  • If set using rgba, the alpha component is ignored. Instead use fill-extrusion-opacity.
  • The extrusion's surfaces are shaded using this color and the root light properties.
  • It has no effect if fill-extrusion-pattern is set.
fill-extrusion-translate
array of numbers
(pixels)
no [0, 0] The geometry's offset.
  • Positive values indicate right and down.
  • Negative values indicate left and up.
fill-extrusion-translate-anchor
string
no map Defines what fill-extrusion-translate is relative to. fill-extrusion-translate needs to be set.
Values:
  • viewport: The translation is relative to the viewport.
  • map: The translation is relative to the map.
fill-extrusion-pattern
string
no none Name of a sprite image to draw extruded fills.
fill-extrusion-height
number
(meters)
no 0 The height to extrude this layer.
fill-extrusion-base
number
(meters)
no 0 The height to extrude the base of this layer.
  • The number must be equal to or greater than 0.
  • The value needs to be less than or equal to fill-extrusion-height.
  • fill-extrusion-height needs to be set.
fill-extrusion-vertical-alignment
boolean
no true If true, the render applies a vertical gradient to the sides of the fill-extrusion-layer. The sides will be shaded darker further down.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
fill-extrusion-opacity ✔ / ✖ ✔ / ✖
fill-extrusion-color ✔ / ✔ ✔ / ✔
fill-extrusion-translate ✔ / ✖ ✔ / ✖
fill-extrusion-translate-anchor ✔ / ✖ ✔ / ✖
fill-extrusion-pattern ✔ / ✔ ✔ / ✔
fill-extrusion-height ✔ / ✔ ✔ / ✔
fill-extrusion-base ✔ / ✔ ✔ / ✔
fill-extrusion-vertical-gradient ✔ / ✖ ✖ / ✖
Heatmap Properties
Name Required Default Value Description
heatmap-radius
number
(pixels)
no 30 Radius of one heatmap point. Number must be equal to or greater than 1.
heatmap-weight
number
no 1 The weight of a point.
  • The greater the weight, the more the point contributes to the heatmap.
  • The number must be equal to or greater than 0.
heatmap-intensity
number
no 1 Unlike heatmap-weight, defines the intensity of the heatmap globally.
heatmap-color
string
no
[
              "interpolate",
              ["linear"],
              ["heatmap-density"],
              0,"rgba(0, 0, 255,0)",
              0.1,"royalblue",
              0.3,"cyan",
              0.5,"lime",
              0.7,"yellow",
              1,"red"
            ]
Defines color of a pixel based on its density value in the heatmap.
heatmap-opacity
number
no 1 Opacity of the heatmap. Number must be between 0 and 1 inclusive.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
heatmap-radius ✔ / ✔ ✔ / ✔
heatmap-weight ✔ / ✔ ✔ / ✔
heatmap-intensity ✔ / ✖ ✔ / ✖
heatmap-color ✔ / ✖ ✔ / ✖
heatmap-opacity ✔ / ✖ ✔ / ✖
Hillshade Properties
Name Required Default Value Description
hillshade-illumination-direction
number
(degrees)
no 335 The direction of the light source. Number must be between 0 and 359 inclusive.
hillshade-illumination-anchor
string
no viewport Light source direction when map is rotated.
Values:
  • viewport: The hillshade illumination is relative to the top of the viewport.
  • map: The hillshade illumination is relative to the north.
hillshade-exaggeration
number
no 0.5 Hillshade's intensity. Number must be between 0 and 1 inclusive.
hillshade-shadow-color
color
no #000000 The shading color of areas that face opposite direction from the light source.
hillshade-highlight-color
number
no #ffffff The shading color of areas that face towards the light source.
hillshade-accent-color
color
no #000000 The shading color of areas like gorges.
SDK Support
Property Name Web SDK
supported / expression
Mobile SDK
supported / expression
hillshade-illumination-direction ✔ / ✖ ✔ / ✖
hillshade-illumination-anchor ✔ / ✖ ✔ / ✖
hillshade-exaggeration ✔ / ✖ ✔ / ✖
hillshade-shadow-color ✔ / ✖ ✔ / ✖
hillshade-highlight-color ✔ / ✖ ✔ / ✖
hillshade-accent-color ✔ / ✖ ✔ / ✖

▲ Return to top

Types

Color

Color type represents a color. The type is written as a JSON string and can be written in different formats: hex values, predefined names, rgb, rgba, hsl, hsla.

{
      "text-color": "#f4f4f4",
      "text-color": "green",
      "text-color": "rgb(255, 255, 255)",
      "text-color": "rgba(255, 255, 255, 1)",
      "text-color": "hsl(240, 100%, 58%)",
      "text-color": "hsla(240, 100%, 58%, 1)"
    }

Boolean

Boolean type can be set to either true or false.

String

String type is a text written in quotes.

Number

Number type is a value that can be an integer or floating point number.

▲ Return to top

Filter

The syntax described below is deprecated. It is recommended to use expressions instead, since they have more flexible syntax than the legacy filters. Expressions syntax and legacy filters syntax cannot be mixed.

Existential Filters

They can be used to check if a feature has a specific attribute or not.

  • ["has", key]: Checks if the feature contains a specified key.
  • ["!has", key]: Checks if the feature does not contain a specified key.

Comparison Filters

They can be used to compare value of feature's attribute.

  • ["==", key, value] is equal to feature[key] == value
  • ["!=", key, value] is equal to feature[key] != value
  • [">", key, value] is equal to feature[key] > value
  • [">=", key, value] is equal to feature[key] >= value
  • ["<", key, value] is equal to feature[key] < value
  • ["<=", key, value] is equal to feature[key] <= value

Set Membership Filters

They can be used to compare value of feature's attribute against mutliple values.

  • ["in", key, v0, ..., vn]: Checks if any of the values (v0, ..., vn) is the same as feature[key].
  • ["!in", key, v0, ..., vn]: Checks if none of the values (v0, ..., vn) is the same as feature[key].

A value must be a number, boolean, or string to compare against the feature's attribute.

Combining Filters

They can be used to combine other filters.

  • ["all", f0, ..., fn]: All of the filters must be true.
  • ["any", f0, ..., fn]: At least one of the filters must be true.
  • ["none", f0, ..., fn]: None of the filters must be true.

(f0, ..., fn) is a set of the filters.

Special Keys

There are some special keys.

  • $type: The feature's type that can be either Point, or LineString, or Polygon.
  • $id: The feature's unqiue id.

(f0, ..., fn) is a set of the filters.

▲ Return to top

Expressions

Expressions can be used as filters, and for any layout properties and paint properties to define formulas for computing values.
Expressions are JSON arrays where:

  • The first element is a string which is the name of the expression.
  • The next elements are arguments to the expression. The arguments can be string, number, boolean, null, or another expression.

Expression syntax:

[expression_name, argument0, argument1, ..., argumentN]

Expression operators

  • Logical operators ! != < <= == > >=
  • Mathematical operators - * / % ^ +
  • String operators
  • Data operators, allow to get features' properties
  • Camera operators, allow to access properties of the current map view, f.e. zoom level

Data expressions

Data expressions allow access to a feature's data and decide how to display it on the map. They can help to differentiate features if they are present in the same layer.


    "text-font": [
        "match",
        ["get", "category"], // get features category
        // if category matches "Large city" or "Capital city" text-font will have '["Noto-Bold"]' value
        "Large city", ["literal", ["Noto-Bold"]],
        "Capital city", ["literal", ["Noto-Bold"]],
        // if category doesnt match any of the above, text-font will use fallback value instead
        ["literal", ["Noto-Regular"]]
    ]

The above example sets the font based on the name of the category of a feature. It uses a get expression to get the name of the feature's category, then sets the right font based on the match.

Camera expression

Camera expresssion is every expression which makes use of the zoom operator.


    "text-size": [
      "interpolate", ["linear"], ["zoom"],
      3, [
        "match",
        ["get", "category"],
        "Country name", 10,
        5
      ],
      5, [
        "match",
        ["get", "category"],
        "Country name", 14,
        8
      ]
    ]

In the above example interpolate is used to define the relation between zoom level and text size basing it on the feature's attribute.

  • The example sets text-size to 10 pixels when the zoom level is 3 or below, and text-size is set to 14 pixels when the zoom level is 5 or above only when category matches Country name.
  • The value is linearly interpolated between 10 and 14 pixels.
  • If a feature's category does not match Country name then fallback values are taken into account.

["zoom"] operator may only be used as the input for interpolate and step expressions. It can be used in an expression inside the let expression.

Examples
[ "step", ["zoom"], ... ]
[ "interpolate", interpolation_type, ["zoom"], ... ]
["let", binding_variables, [ "step", ["zoom"], ... ]]
["let", binding_variables, [ "interpolate", interpolation_type, ["zoom"], ... ]]

The layout property camera expression is evaluated only on integer levels, while the paint property camera expression is evaluated on every zoom level change.

Composition

Expressions can contain other expressions and operators within themselves. It allows you to decide how to display features based on their attributes and other factors like zoom level.


    "text-size": [
      "interpolate", ["linear"], ["zoom"],
      3, 5,
      5, [
        "match",
        ["get", "category"],
        "Country name", 14,
        8
      ]
    ]

Type system

Expressions are type safe. Each of the them has a specified return type and arguments' types. Types of arguments passed to the expressions are checked by the SDK. For instance, the return type of the filter property has to be boolean.

Types can be unknown when using data expressions. The SDK checks if the value's type of the feature's data is valid for a specific property.
If it is not, then the default value will be used instead.

Types can be unknown when using data expressions like ["<", ["get", "priority"], ["get", "category"]].
To be sure if a feature's data is the right type type assertion operators should be used, for instance, ["<", ["number", ["get", "priority"]], ["number" ["get", "category"]]].
A failed check means that the property will use the default value instead.

Conversion between types does not happen automatically. The only exception is where a property expects color, then the color represented as a string is converted to a color value.
If there is a need to convert other types, then type conversion operators have to be used.

Assertion operators

  • number
  • string
  • boolean
  • array

Type conversion operators

  • to-number
  • to-string
  • to-boolean
  • to-color
Example
"text-size": ["to-number", ["get", "size"]]

Expression reference

Types

This section describes type conversion operators and operators which can be useful for testing purposes. Most of the time they are not needed, but they can be in the cases described above.

array

Asserts that the input is an array. The size and the type can be also checked if needed. If the assertion fails the expression is aborted.

  • type: type of the array. (optional)
  • size: size of the array. (optional)
  • input: input value to be checked.
["array", input]: array
["array",
type: "string" | "number" | "boolean",
input]: array<type>
["array",
type: "string" | "number" | "boolean",
size: number (literal),
input]: array<type, size>

boolean

Asserts that the input is a boolean. If multiple values are provided, they are evaluated in order until one of them passes the check. If the assertion fails the expression is errored.

  • input: input value to be checked.
  • fallback: fallback values to be checked. (optional)
["boolean", input: value]: boolean
["boolean", input: value, fallback: value, ..., fallback: value]: boolean

collator

Returns collator which is used for locale-dependent comparisons.

  • case-sensitive: true if comparison should be case-sensitive, false otherwise.
  • diacritic-sensitive: true if comparison should be diacritic-sensitive, false otherwise.
  • locale: The IETF language tag. If none is provided, then the default locale is used. If a requested locale is not available, the system-defined fallback locale will be used.
["collator",
    { "case-sensitive": boolean, "diacritic-sensitive": boolean, "locale": string}]: collator

format

Returns formatted text to use within text-field.

  • input: string to be formatted.
  • options: defines how to format input.
    • text-color: if set, it overrides the root text-color paint property.
    • text-font: if set, it overrides the root text-font layout property.
    • font-scale: scalling factor relative to the root text-size layout property.
["format",
    input1: string, option1: { "font-scale": number, "text-font": array<string>, "text-color": color },
    input2: string, option2: { "font-scale": number, "text-font": array<string>, "text-color": color },
    ...,
    inputN: string, optionN: { "font-scale": number, "text-font": array<string>, "text-color": color }]: formatted

literal

Returns a literal array or object value.

["literal", [...]]: array<T, N>
["literal", {...}]: object

number

Asserts that the input is a number. If multiple values are provided, they are evaluated in order until one of them passes the check. If the assertion fails the expression is errored.

  • input: input value to be checked.
  • fallback: fallback values to be checked. (optional)
["number", input: value]: number
["number", input: value, fallback: value, ..., fallback: value]: number

number-format

Returns number as a string using specified formatting rules.

  • input: input number to be returned as a string.
  • options: formatting rules.
    • locale: locale to use, needs to be BCP 47 langauge tag.
    • currency: used for currency style formatting, needs to be ISO 4217 code.
    • min-fraction-digits: minium number of fractional digits to include.
    • max-fraction-digits: maximum number of fractional digits to include.

object

Asserts that the input is an object. If multiple values are provided, they are evaluated in order until one of them passes the check. If the assertion fails the expression is errored.

  • input: input value to be checked.
  • fallback: fallback values to be checked. (optional)
["object", input: value]: object
["object", input: value, fallback: value, ..., fallback: value]: object

string

Asserts that the input is a string. If multiple values are provided, they are evaluated in order until one of them passes the check. If the assertion fails the expression is errored.

  • input: input value to be checked.
  • fallback: fallback values to be checked. (optional)
["string", input: value]: string
["string", input: value, fallback: value, ..., fallback: value]: string

to-boolean

Converts the input value to a boolean. Converted boolean is false when one of the provided values is an empty string, false, NaN, 0 or null.
Otherwise the converted boolean is true.

  • input: input value to be converted.
["to-boolean", input: value]: boolean

to-color

Converts the input value to a color. If multiple values are provided, they are evaluated in order until one of them is successfully converted.
If none of them has been converted, the expression is errored.

  • input: input value to be converted.
["to-color", input: value, fallback: value, ..., fallback: value]: color

to-number

Converts the input value to a number. If the provided input value is either null or false the converted number will be equal to 0.
The algorithm "ToNumber Applied to the String Type" of the ECMAScript Language Specification is used to convert string into number.
If multiple values are provided, they are evaluated in order until one of them is successfully converted.
If none of them has been converted, the expression is errored.

  • input: input value to be converted.
["to-number", input: value, fallback: value, ..., fallback: value]: number

to-string

Converts the input value to a string. Boolean values are converted to either "false" or "true". Null value is converted to "".
For the numbers, "NumberToString" algorithm of the ECMAScript Language Specification is used for conversion.
Color values are converted into "rgba(r, g, b, a)", where r, g, b ∈ [0; 255], and a ∈ [0; 1].

  • input: input value to be converted.
["to-string", input: value]: string

typeof

Returns the type of the input values as string.

  • input: input value to be converted.
["typeof", input: value]: string
SDK Support
Expression Name Web SDK Mobile SDK
array
boolean
collator
format
image
literal
number
number-format
object
string
to-boolean
to-color
to-number
to-string
typeof

Feature data

accumulated

Returns the accumulated value of a cluster property. Can only be used in the clusterProperties.

["accumulated"]: value

feature-state

Returns the property from the current feature's state. If the requested property is not available, then null will be returned.
To identify features, use their id attribute which is an integer or a string castable to an integer.
The feature's state has to be set programmatically on each future since they are not part of vector tile data or GeoJSON.

  • property: property name to get.
["feature-state", property: string]: value

geometry-type

Returns the feature's geometry type as string.

Values:

  • Point
  • MultiPoint
  • LineString
  • MultiLineString
  • Polygon
  • MultiPolygon
["geometry-type"]: string

id

Returns a feature's id.

["id"]: value

line-progress

Gets the progress along a gradient line.

["line-progress"]: number

properties

Returns a feature's properties.

["properties"]: object
SDK Support
Expression Name Web SDK Mobile SDK
accumulated
feature-state
geometry-type
id
line-progress
properties

Lookup

at

Returns an item from an array.

  • pos: item's position.
  • array: array from which to get an item.
["at", pos: number, array: array]: item

get

Returns a property value from the feature's properties or provided object. Returns null if the property is not available.

  • key: if object is not provided then it is the name of current feature's property, otherwise it is the name of the key to get from the provided object.
  • object: an object to get value from. (optional)
["get", key: string]: value
["get", key: string, object: object]: value

has

Checks if the current feature's property or provided object's key exists.

  • key: if object is not provided then it is the name of current feature's property, otherwise it is the name of the key to get from the provided object.
  • object: an object to get value from. (optional)
["has", key: string]: boolean
["has", key: string, object: object]: boolean

length

Returns the length of a string or array.

  • input: string or array to check the length.
["length", input: string | array]: number
SDK Support
Expression Name Web SDK Mobile SDK
at
get
has
length

Decision

The following expressions can be used to add conditional logic to the styles.

!

Logical negation.

  • input: boolean to negate.
["!", input: boolean]: boolean

!=

Returns true if inputs are different, false otherwise.
If the types of the input values can be deduced at the parse time and happen to be different, then the comparison will produce an error.
If the types of the input values happen to be different at the runtime, then the result will be always false.

  • input1: value to compare.
  • input2: value to compare.
  • collator: collator for locale-dependent string comparison. (optional)
["!=", input1: value, input2: value]: boolean
["!=", input1: value, input2: value, collator: collator]: boolean

<

Returns true if the first input is less than the second one, false otherwise.
The types of the inputs need both to be strings or numbers. If during runtime or parsing time they happen to be different, comparison will produce an error.

  • input1: value to compare.
  • input2: value to compare.
  • collator: collator for locale-dependent string comparison. (optional)
["<", input1: value, input2: value]: boolean
["<", input1: value, input2: value, collator: collator]: boolean

<=

Returns true if the first input is less than or equal to the second one, false otherwise.
The types of the inputs need both to be strings or numbers. If during runtime or parsing time they happen to be different, comparison will produce an error.

  • input1: value to compare.
  • input2: value to compare.
  • collator: collator for locale-dependent string comparison. (optional)
["<=", input1: value, input2: value]: boolean
["<=", input1: value, input2: value, collator: collator]: boolean

==

Returns true if the inputs are equal, false otherwise.
If the types of the input values can be deduced at the parse time and happen to be different, then the comparison will produce an error.
If the types of the input values happen to be different at the runtime, then the result will be always false.

  • input1: value to compare.
  • input2: value to compare.
  • collator: collator for locale-dependent string comparison. (optional)
["==", input1: value, input2: value]: boolean
["==", input1: value, input2: value, collator: collator]: boolean

>

Returns true if the first input is greater than the second one, false otherwise.
The types of the inputs need both to be strings or numbers. If during runtime or parsing time they happen to be different, comparison will produce an error.

  • input1: value to compare.
  • input2: value to compare.
  • collator: collator for locale-dependent string comparison. (optional)
[">", input1: value, input2: value]: boolean
[">", input1: value, input2: value, collator: collator]: boolean

>=

Returns true if the first input is greater than or equal to the second one, false otherwise.
The types of the inputs need both to be strings or numbers. If during runtime or parsing time they happen to be different, comparison will produce an error.

  • input1: value to compare.
  • input2: value to compare.
  • collator: collator for locale-dependent string comparison. (optional)
[">=", input1: value, input2: value]: boolean
[">=", input1: value, input2: value, collator: collator]: boolean

all

Returns true if all inputs are true, false otherwise.
If one of the inputs is false, then the remaining inputs are not checked and the expression returns false.

  • input: input expression.
["all", input1: boolean, input2: boolean, ..., inputN: boolean]: boolean
["all", input1: boolean, input2: boolean, ..., inputN: boolean]: boolean

any

Returns true if any of the inputs is true, false otherwise.
If one of the inputs is true, then the remaining inputs are not checked and the expression returns true.

  • input: input expression.
["all", input1: boolean, input2: boolean, ..., inputN: boolean]: boolean
["all", input1: boolean, input2: boolean, ..., inputN: boolean]: boolean

case

Returns a value of the first input expression that evaluates to true.

  • input: input expression.
  • output: value to return when the input evaluates to true.
  • fallback: value to return when none of the inputs expressions evaluates to true.
["case",
    input1: boolean, output1: value,
    input2: boolean, output2: value,
    ...,
    fallback: value]: value

coalesce

Returns the first non-null value.

  • input: input expression.
["coalesce", input1: value, input2: value, ..., inputN: value]: value

match

Returns the output whose label matches the input. The input can be any expression. Labels must have unique names.
If input values match no label then fallback is returned.
The label can only be:

  • A single literal number or string.
  • An array of literals, numbers, or strings. If the input matches any of the values in the array, then output is returned
["match",
    input: number | string,
    label: number | string | [number, number, ..., number] | [string, string, ..., string], output: value,
    label: number | string | [number, number, ..., number] | [string, string, ..., string], output: value,
    ...
    label: number | string | [number, number, ..., number] | [string, string, ..., string], output: value,
    fallback: value]: value
SDK Support
Expression Name Web SDK Mobile SDK
!
!=
<
<=
==
>
>=
all
any
case
coalesce
match

Ramps, scales, curves

interpolate

Interpolates between pairs of the input and output values. Stop input values must be in ascending order.
Interpolate types:

  • linear: ["linear"] interpolates linearly between the pair of stops.
  • exponential: ["exponential", base] interpolates exponentially between the pair of stops. High base values increase output values more towards the end of the range while low values increase output linearly.
  • cubic-bezier: ["cubic-bezier", x1, y1, x2, y2] interpolates using the cubic bezier curve.
["interpolate",
    interpolation: interpolationType
    input: number,
    stopInput1: number, stopOutput1: number, array<number>, color,
    stopInput2: number, stopOutput2: number, array<number>, color,
    ...
    stopInputN: number, stopOutputN: number, array<number>, color]: number, array<number>, color

interpolate-hcl

Interpolates between pairs of the input and output values. Stop input values must be in ascending order. Interpolation is performed in the Hue-Chroma-Luminance color space.
Interpolate types:

  • linear: ["linear"] interpolates linearly between the pair of stops.
  • exponential: ["exponential", base] interpolates exponentially between the pair of stops. High base values increase output values more towards the end of the range while low values increase output linearly.
  • cubic-bezier: ["cubic-bezier", x1, y1, x2, y2] interpolates using the cubic bezier curve.
["interpolate-hcl",
      interpolation: interpolationType
      input: number,
      stopInput1: number, stopOutput1: color,
      stopInput2: number, stopOutput2: color,
      ...
      stopInputN: number, stopOutputN: color]: color

interpolate-lab

Interpolates between pairs of the input and output values. Stop input values must be in ascending order. Interpolation is performed in the CIELAB color space.
Interpolate types:

  • linear: ["linear"] interpolates linearly between the pair of stops.
  • exponential: ["exponential", base] interpolates exponentially between the pair of stops. High base values increase output values more towards the end of the range while low values increase output linearly.
  • cubic-bezier: ["cubic-bezier", x1, y1, x2, y2] interpolates using the cubic bezier curve.
["interpolate-lab",
      interpolation: interpolationType
      input: number,
      stopInput1: number, stopOutput1: color,
      stopInput2: number, stopOutput2: color,
      ...
      stopInputN: number, stopOutputN: color]: color

step

Interpolates between pairs of the input and output values. Stop input values must be in ascending order.

["step",
      input: number,
      stopOutput0: value,
      stopInput1: number, stopOutput1: value,
      stopInput2: number, stopOutput2: value,
      ...
      stopInputN: number, stopOutputN: value]: value
SDK Support
Expression Name Web SDK Mobile SDK
interpolate
interpolate-hcl
interpolate-lab
step

Variable binding

let

Binds expression to variables.

["let", variable: string, any, ..., value]: value

var

References variable bound using "let".

["var", variable: string]: bound expression's type
SDK Support
Expression Name Web SDK Mobile SDK
let
var

String

concat

Concats pass inputs, converting them to a string beforehand.

["concat", input1: value, input2: value, ..., inputN: value]: string

downcase

Converts the input string to lowercase.

["downcase", input: string]: string

is-supported-script

Checks if the input renders as it should without losing meaning.

["is-supported-script", input: string]: boolean

resolved-locale

Returns the language tag of the locale used by collator. It can be used to check if the requested locale has been successfully loaded.

["resolved-locale", input: collator]: string

upcase

Converts the input string to uppercase.

["upcase", input: string]: string
SDK Support
Expression Name Web SDK Mobile SDK
concat
downcase
is-supported-script
resolved-locale
upcase

Color

rgb

Creates color based on red, green, and blue input values with the alpha component set to 1. Input colors ∈ [0; 255].

["rgb", red: number, green: number, blue: number]: color

rgba

Creates color based on red, green, blue, and alpha components. Input colors ∈ [0; 255]. Alpha component ∈ [0; 1].

["rgba", red: number, green: number, blue: number, alpha: number]: color

to-rgba

Returns an array that contains input rgba colors.

["to-rgba", input: color]: array<number, 4>
SDK Support
Expression Name Web SDK Mobile SDK
rgb
rgba
to-rgba

Math

-

Subtracts the second input from the first one. If there is only one input, then the input is subtracted from 0.

["-", input: number, input: number]: number
["-", input: number]: number

*

Returns the product of the passed numbers.

["*", input1: number, input2: number, ..., inputN: number]: number

/

Returns the quotient of the two numbers.

["/", input1: number, input2: number]: number

%

Returns the remainder of the division of the first input by the second one.

["%", input1: number, input2: number]: number

^

Returns the result of raising the input to the power.

["^", input: number, power: number]: number

+

Returns the result of raising the input to the power.

["+", input1: number, input2: number, ..., inputN: number]: number

sqrt

Returns the square root of the input.

["sqrt", input: number]: number

abs

Returns the absolute value of the input.

["abs", input: number]: number

sin

Returns the sine of the input.

["sin", input: number]: number

cos

Returns the cosine of the input.

["cos", input: number]: number

tan

Returns the tangent of the input.

["tan", input: number]: number

asin

Returns the arcsine of the input.

["asin", input: number]: number

acos

Returns the arccosine of the input.

["acos", input: number]: number

atan

Returns the arctangent of the input.

["atan", input: number]: number

ceil

Returns the smallest integer that is greater than or equal to the input.

["ceil", input: number]: number

e

Returns the mathematical constant e.

["e"]: number

pi

Returns the mathematical constant π.

["pi"]: number

ln

Returns the natural logarithm of the input.

["ln", input: number]: number

ln2

Returns the mathematical constant ln(2).

["ln2", input: number]: number

log10

Returns the base ten logarithm of the input.

["log10", input: number]: number

log2

Returns the base two logarithm of the input.

["log2", input: number]: number

max

Returns the maximum number of the inputs.

["max", input1: number, input2: number, ..., inputN: number]: number

min

Returns the minimum number of the inputs.

["min", input1: number, input2: number, ..., inputN: number]: number

round

Rounds the input to the nearest integer. Halfway values are rounded away from zero.

["round", input: number]: number

floor

Returns the largest integer that is less than or equal to the input.

["floor", input: number]: number
SDK Support
Expression Name Web SDK Mobile SDK
-
*
/
%
^
+
sqrt
abs
sin
cos
tan
asin
acos
atan
ceil
e
pi
ln
ln2
log10
log2
max
min
round
floor

Zoom

zoom

Returns the current zoom level.
In the layout and paint properties, the zoom expression may only be used as an input in the top level step or interpolate expression.

["zoom"]: number
SDK Support
Expression Name Web SDK Mobile SDK
zoom

Heatmap

heatmap-density

Returns estimated density of the center of a pixel in a heatmap layer. This is useful to determine how many data points are crowded around a pixel.

["heatmap-density"]: number
SDK Support
Expression Name Web SDK Mobile SDK
heatmap-density

▲ Return to top

The TomTom vector map style specification is derived from the Style Specification of Mapbox, which is licensed under the BSD 3-Clause "New" or "Revised" License as described below.
Modifications and additions are © TomTom, and are provided under the same license terms.
__

Mapbox Style Specification

Copyright (c) 2019, Mapbox
__

All rights reserved.
__

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
__

* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

* Neither the name of Mapbox GL JS nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
__

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR

CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

You are here