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

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

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.

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

✔ ✘

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.

Index file - JSON
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

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.

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

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


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

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
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.

Type formats - JSON
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.

Data expressions example
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.

Camera expression example
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

let expression example
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.

Expression composition example
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:

Unknown types example
["<", ["get", "priority"], ["get", "category"]]

To be sure if a feature's data is the right type, type assertion operators should be used, for instance,

Type assertion operators example
["<", ["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
Type conversion operator 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.
Type assertion operators example
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)
boolean input and fallback example
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.
collater example
["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 example
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.

Literal array and object example
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 and fallback and example
["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 and fallback example
["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 and fallback example
["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.
input value conversion example
["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.
input value conversion example
["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.
input value conversion example
["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.
input value conversion example
["to-string", input: value]: string

typeof

Returns the type of the input values as string.

  • input: input value to be converted.
input value conversion example
["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 example
["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.
property example
["feature-state", property: string]: value

geometry-type

Returns the feature's geometry type as string.

Values:

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

id

Returns a feature's id.

feature id example
["id"]: value

line-progress

Gets the progress along a gradient line.

gradient line progress example
["line-progress"]: number

properties

Returns a feature's properties.

feature properties example
["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.
Returning an item from an array example
["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)
Returning property values example
["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)
Checking key examples
["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.
Returning a length example
["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.

Negating a boolean example
["!", 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).
Deducing input examples
["!=", 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).
Comparing input value examples
["<", 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).
Comparing input value examples
["<=", 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).
Deducing input value examples
["==", 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).
Deducing input value examples
[">", 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).
Comparing input value examples
[">=", 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.
Checking input examples
["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.
Checking input examples
["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.
Returns value of the first true input expression examples
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.
Returns the first non-null value example
["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.
Output label matches input label
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.
Interpolates pairs of input and output values
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.
Interpolates between pairs of input and output values
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.
Interpolates between pairs of input and output values
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.

Interpolates between pairs of input and output values
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.

Binds expression to variables
["let", variable: string, any, ..., value]: value

var

References variable bound using "let".

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.

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

downcase

Converts the input string to lowercase.

Converts the input string
["downcase", input: string]: string

is-supported-script

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

Checks input rendering
["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.

Returns the locale language tag
["resolved-locale", input: collator]: string

upcase

Converts the input string to uppercase.

Converts input string to uppercase
["