Map Style Specification

Service version: 1
Last edit: 2022.08.15

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
nononeName of the style.
version
number
yesnone

Version of the style specification.


Value: 8.

zoom
number
nonone

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
nonone

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
yesnone

Data source. Properties of the source object can be found at source properties.

light{}
object
nonone

Light source. Properties of the light{} object can be found at light properties.

glyphs{}
object

no /
yes (if any layer uses the 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
nonone

Defines the default transition to use across the style. Properties of the transition object can be found at transition properties.

layers
array of objects
yesnone

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.

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
nononeURL to a resource.
tiles
array of strings
nonone

An array of the URLs to a resource. This property can contain one or more URLs.

attribution
string
nononeAttribution 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
nononeURL to a resource.
tiles
array of strings
nonone

An array of the URLs to a resource. This property can contain one or more URLs.

attribution
string
nononeAttribution 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
nononeURL to a resource.
tiles
array of strings
nonone

An array of the URLs to a resource. This property can contain one or more URLs.

attribution
string
nononeAttribution 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
yesnoneURL 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
nononeAttribution 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
nonone

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
yesnoneURL to an image resource.
coordinates
array of arrays of numbers
yesnone

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
yesnoneURLs to video resources.
coordinates
array of arrays of numbers
yesnone

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

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.

1{
2 "145": {
3 "width": 24,
4 "height": 24,
5 "x": 697,
6 "y": 600,
7 "pixelRatio": 1
8 }
9}

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.

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.

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

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

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
yesnoneID of the layer. Must be unique.
type
string
yesnone

Type of the layer.


Values:
  • fill
  • symbol
  • circle
  • raster
  • background
  • line
  • heatmap
  • fill-extrusion
  • hillshade
metadata{}
object
nononeAttributes that do not affect rendering.
source
string

no / yes (if type is not equal to background)

noneName of a source to be used.
source-layer
string

no / yes (if source is equal to vector)

noneA layer to use from vector source.
minzoom
number
nonone

The minimum zoom level to draw the layer. Number must be between 0 and 22 inclusive.

maxzoom
number
nonone

The maximum zoom level to draw the layer. Number must be between 0 and 22 inclusive.

filter

array


(filter)

nonone

If the feature does not match the condition, then it is not drawn on the map.

layout{}
object
nonone

Layout properties. Properties of the layout{} object can be found at layout properties.

paint{}
object
nonone

Paint properties. Properties of the paint{} object can be found at paint properties.

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
string
✔ / ✖ ✔ / ✖

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
string
✔ / ✖ ✔ / ✖

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
string
✔ / ✖ ✔ / ✖
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
nononeUsed 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
nononeName 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
nononeText 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
nonone

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
string
✔ / ✖ ✔ / ✖
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
string
✔ / ✖ ✔ / ✖

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
string
✔ / ✖ ✔ / ✖

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
string
✔ / ✖ ✔ / ✖

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
string
✔ / ✖ ✔ / ✖

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
string
✔ / ✖ ✔ / ✖

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
nononeName 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
nonone

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
nononeName 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
nononeName 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)

nonone

Defines lengths of the dashes and gaps. The lengths are scaled by the line-width.

line-gradient
string
nonone

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)

nonone

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
nononeName 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
1[
2 "interpolate",
3 [
4 "linear"
5 ],
6 [
7 "heatmap-density"
8 ],
9 0,
10 "rgba(0, 0, 255,0)",
11 0.1,
12 "royalblue",
13 0.3,
14 "cyan",
15 0.5,
16 "lime",
17 0.7,
18 "yellow",
19 1,
20 "red"
21]

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✔ / ✖ ✔ / ✖

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.

1{
2 "text-color": "#f4f4f4",
3 "text-color": "green",
4 "text-color": "rgb(255, 255, 255)",
5 "text-color": "rgba(255, 255, 255, 1)",
6 "text-color": "hsl(240, 100%, 58%)",
7 "text-color": "hsla(240, 100%, 58%, 1)"
8}

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.

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
  • ["&lt;", key, value] is equal to feature[key] < value
  • ["&lt;=", 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.

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: ! != &lt; &lt;= == &gt; &gt;=
  • Mathematical operators: - * / % ^ +
  • String operators
  • Data operators: allow the getting of features' properties
  • Camera operators: allow access to properties of the current map view, for example, 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.

1"text-font": [
2 "match",
3 ["get", "category"], // get features category
4 // if category matches "Large city" or "Capital city" text-font will have '["Noto-Bold"]' value
5 "Large city", ["literal", ["Noto-Bold"]],
6 "Capital city", ["literal", ["Noto-Bold"]],
7 // if category doesnt match any of the above, text-font will use fallback value instead
8 ["literal", ["Noto-Regular"]]
9]

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.

1"text-size": [
2 "interpolate", ["linear"], ["zoom"],
3 3, [
4 "match",
5 ["get", "category"],
6 "Country name", 10,
7 5
8 ],
9 5, [
10 "match",
11 ["get", "category"],
12 "Country name", 14,
13 8
14 ]
15]

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.

The ["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

1[ "step", ["zoom"], ... ]
2[ "interpolate", interpolation_type, ["zoom"], ... ]
3[ "let", binding_variables, [ "step", ["zoom"], ... ]]
4[ "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.

1"text-size": [
2 "interpolate", ["linear"], ["zoom"],
3 3, 5,
4 5, [
5 "match",
6 ["get", "category"],
7 "Country name", 14,
8 8
9 ]
10]

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
"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.
1["array", input]: array
2
3["array",
4type: "string" | "number" | "boolean",
5input]: array<type>
6
7["array",
8type: "string" | "number" | "boolean",
9size: number (literal),
10input]: 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)
1["boolean", input: value]: boolean
2
3["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.
1["format",
2 input1: string, option1: { "font-scale": number, "text-font": array<string>, "text-color": color },
3 input2: string, option2: { "font-scale": number, "text-font": array<string> "text-color": color },
4 ...,
5 inputN: string, optionN: { "font-scale": number, "text-font": array<string>, "text-color": color }]: formatted

literal

Returns a literal array or object value.

1["literal", [...]]: array<T, N>
2
3["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</code></pre>
["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, the "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.
1["case",
2 input1: boolean, output1: value,
3 input2: boolean, output2: value,
4 ...,
5 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.
1["match",
2 input: number | string,
3 label: number | string | [number, number, ..., number] | [string, string, ..., string], output: value,
4 label: number | string | [number, number, ..., number] | [string, string, ..., string], output: value,
5 ...
6 label: number | string | [number, number, ..., number] | [string, string, ..., string], output: value,
7 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.
1["interpolate",
2 interpolation: interpolationType
3 input: number,
4 stopInput1: number, stopOutput1: number, array&lt;number&gt;, color,
5 stopInput2: number, stopOutput2: number, array&lt;number&gt;, color,
6 ...
7 stopInputN: number, stopOutputN: number, array&lt;number&gt;, color]: number, array&lt;number&gt;, 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.
1["interpolate-hcl",
2 interpolation: interpolationType
3 input: number,
4 stopInput1: number, stopOutput1: color,
5 stopInput2: number, stopOutput2: color,
6 ...
7 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.
1["interpolate-lab",
2 interpolation: interpolationType
3 input: number,
4 stopInput1: number, stopOutput1: color,
5 stopInput2: number, stopOutput2: color,
6 ...
7 stopInputN: number, stopOutputN: color]: color

step

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

1["step",
2 input: number,
3 stopOutput0: value,
4 stopInput1: number, stopOutput1: value,
5 stopInput2: number, stopOutput2: value,
6 ...
7 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, and 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, ...,