Style expressions reference

Understand expressions used in style rules to select features, calculate values, and respond to map state. Expressions are JSON arrays that can access feature properties, read the current zoom level, and perform conditional logic.

Basic Types

array

The array type stores an array of value types. To create an array value use literal expression.

Examples:

["literal", [1, 2] ] // returns an array of real numbers.

["literal", [1, "2", 3] ] // returns an array of numbers and strings

color

The color type stores a renderable color. A color value can be represented as a string.
Supported string formats are:

hex format "#rgb", "#rgba", "#rrggbb", and "#rrggbbaa" with r,g,b,a in range [0-9, a-f].
css color functions "rgb(r,g,b)", with r,g,b in range [0, 255]. Values outside the ranges are clamped to the range boundary.

Examples:

"#00ff7f" -> opaque color with RGB channels 0, 255, 127 (SpringGreen)

"#f0f" -> opaque color with RGB channels 255, 0, 255 (Magenta)

dictionary

The dictionary type stores key-value pairs. The dictionary can be queried using get and has expressions.
To create a dictionary value use literal expression.

Example:

["literal", {"a": 1, "b": 2}]

vector2d

The vector2d type stores a 2d vector of numbers. To create a vector2d value, use make-vector expression.

Example:

["make-vector", 10, 20] // returns [10, 20]

vector3d

The vector3d type stores a 3d vector of numbers. To create a vector3d value, use make-vector expression.

Example:

["make-vector", 4.5, 5.5, 6.7] // returns [4.5, 5.5, 6.7]

vector4d

The vector4d type stores a 4d vector of numbers. To create a vector4d value, use make-vector expression.

Example:

["make-vector", -2, 4, 90, -234] //  return [-2, 4, 90, -234]

Expressions

!

Returns false if its value can be converted to true; otherwise, returns true.

Example:

["!", value]

!=

Returns true if the values are not equal. number and string types are supported.

Example:

["!=", value, value]

!has

Returns a boolean indicating if the current feature or the given dictionary does not have the specified property. By feature, we understand a customizable map item, like roads, polygons etc.

["!has", name]
["!has", name, dictionary]

The !has expression is equivalent to the negation of the has expression:

["!has", name] /* is same as */ ["!", ["has", name]]
["!has", name, dictionary] /* is same as */  ["!", ["has", name, object]]

<

Returns true if the first value is less than the second value.

["<", number, number]

<=

Returns true if the first value is less than or equal to the second value.

["<=", number, number]

==

Returns true if the values are equal. number and string types are supported.

["==", value, value]

>

Returns true if the first value is greater than the second value.

[">", number, number]

>=

Returns true if the first value is greater than or equal to the second value.

[">=", number, number]

all

Returns true if all the sub expressions evaluate to true.

["all", expression...] // boolean

Example:

"definitions" : {
    "my_condition_1": true,
    "my_condition_2": false,
    "my_condition_3": true

}
["all",
    ["ref", "my_condition_1"],
    ["ref", "my_condition_2"],
    ["ref", "my_condition_3"]
] // returns false since my_condition_2 is false

any

Returns true if any sub expression evaluates to true.

["any", expression...] // boolean

Example:

"definitions" : {
    "my_condition_1": true,
    "my_condition_2": false,
    "my_condition_3": true

}
["any",
    ["ref", "my_condition_1"],
    ["ref", "my_condition_2"],
    ["ref", "my_condition_3"]
] // returns true since my_condition_1 is true

case

Evaluates the conditions in order and returns the first result where the condition evaluates to true. The fallback are returned if no conditions evaluates to true.

["case",
  condition1, result1,
  ...
  conditionN, resultN,
  fallback
]

Example:

"definitions" : {
    "my_condition_1": false,
    "my_condition_2": false,
    "my_condition_3": true

}
["case",
    ["ref", "my_condition_1"],
    10,
    ["ref", "my_condition_2"],
    20,
    ["ref", "my_condition_3"],
    40,
    80 // fallback value
] // returns 40 since my_condition_3 is true

get

Gets the property value of the current feature or a dictionary. Returns null if the property is not present. By feature, we understand a customizable map item, like roads, polygons etc.


["get", name] // `name` can be an expression, but that disables optimization and evaluation will be much slower.
["get", name, dictionary]

Examples:

To illustrate the use of get expression, let us consider a case where the rendered map contains a layer called 'Roads'.
Each feature (i.e. road) in the layer contains the property "road_width", expressed in meters.
Ideally we would like to use the "road_width" property of each feature in the style. To do that, we employ the
get expression. In the style below we set the style attribute "width" to the value of "road_width" property. In this manner, each styled line will have the width
that is defined in the "road_width" property.

{
  "styles": [
    {
      "layer": "Roads",
      "technique": "line",
      "attr": {
        "width": ["get", "road_width"] // returns the width in meter of the current road
        }
     }
  ]
}

In the following example, literal returns a dictionary with two keys "a" and "b". get expression will return the value of key "a"


["get", "a", ["literal", {"a": 1, "b": 2}]] // returns 1

has

Returns a boolean indicating if the current feature or the given dictionary has the specified property. By feature, we understand a customizable map item, like roads, polygons etc.

["has", name] // `name` can be an expression, but that disables optimization and evaluation will be much slower.
["has", name, dictionary]

Examples:

Consider again a rendered map that contains a layer called 'Roads'. This time, not all features in the layer contain the property "road_width", expressed in meters: some do, and some do not. You want to use the "road_width" property of each feature in the style, but you also need to handle the features that do not have this property. Use the has expression to check whether a feature has the "road_width" property. For features that do not have it, set a default line width.

{
  "styles": [{
    "layer": "Roads",
    "technique": "line",
    "attr": {
      "width": ["case" ["has", "road_width"], // returns true if the current road has "road_width" property
        ["get", "road_width"], // if the current road has "road_width" property, we set line width to "road_width" value
        10
      ] // else we set the line width to 10 meters
    }
  }]
}

In the following example, literal returns a dictionary with two keys "a" and "b". The has expression returns true.

["has", "a", ["literal", {"a": 1, "b": 2}]] // returns true

interpolate

Creates interpolation of given values, based on another stop variable.
Available interpolation types are ["linear"] and ["step"].

["interpolate", ["linear"], ["zoom"],
   stop1, value1,
   ...
   stopN, valueN,
]

Example:

// ["zoom"] returns 9
["interpolate", ["linear"], ["zoom"], 8, 20, 10, 40] // returns 30

literal

Returns a dictionary or an array as specified in json_document.

["literal", json_document]

Example:

["literal", {"a": 1, "b": 2}] // returns a dictionary with keys "a" and "b"
["literal", [1, 2, 3]] // returns an array

make-vector

Constructs two, three, or four dimensional vector from numbers.

["make-vector", number, number]
["make-vector", number, number, number]
["make-vector", number, number, number, number]

Examples:

["make-vector", 10, 20] // returns [10, 20]
["make-vector", 4.5, 5.5, 6.7] // returns [4.5, 5.5, 6.7]
["make-vector", -2, 4, 90, -234] //  return [-2, 4, 90, -234]
["make-vector", 10, "20"] // returns null, does not support strings

match

Compares value with the labels and returns the result of the first match. If the value does not match any label fallback is returned. A label must be a number, a string, or an array of those. If value and label differ in type, then fallback is be returned.

["match",
  value,
  label1, result1,
  ...
  labelN, resultN,
  fallback
]

Example:

"definitions" : {
    "my_value": 10
}
["match",
    ["ref", "my_value"],
    20,
    "Value is 20", // result 1
    10,
    "Value is 10", // result 2
    "No match was found" // fallback value
] // returns "Value is 10"

none

Returns true if no sub expression evaluates to true.

["none", expression...]

Example:

"definitions" : {
    "my_condition_1": true,
    "my_condition_2": false,
    "my_condition_3": true

}
["none",
    ["ref", "my_condition_1"],
    ["ref", "my_condition_2"],
    ["ref", "my_condition_3"]
] // returns false since my_condition_1 is true

pixel-world-scale

Converts screen pixels to world units (meters).

["pixel-world-scale", number]

Example:

Consider the case where you want to render a polyline with a width of ten pixels. Given that the width attribute of the line techniques requires meters, the straightforward way to render a polyline with a width of 10 pixels is by using pixel-world-scale.

{
  "styles": [
      {
        "layer": "MyRoads",
        "technique": "line",
        "attr": {
          "width": ["pixel-world-scale", 10.0] // returns the width in meter that is equivalent to 10 screen pixels. The line will be rendered with a width of 10 screen pixels
      }
    }
  ]
}

ref

References a value definition or an expression definition that can be evaluated to a value. Returns null if the definition cannot be found.

["ref", string]

Example:


"definitions" : {
    "my_definition_1": 4,
    "my_definition_2": true,
    "my definition_3": ["+", 1, 2]

}
["ref", "my_definition_1"] // returns 4
["ref", "my_definition_2"] // returns true
["ref", "my_definition_3"] // returns 3
["ref", "my_definition_4"] // returns null, the definition cannot be found.

rgb

Creates a color from the RGB components. The components must be integers between 0 and 255. Values outside the range are clamped to the range border.

["rgb", number, number, number]

Example:

["rgb", 1, 2, 3] // returns opaque color with RGB channels 1, 2, 3

step

Evaluates the given piecewise function. Returns default value if input is less than the first stop. Otherwise returns the value associated with the stop that is greater than or equal to input.

Example:

["step", ["zoom"], default value, stop1, value1, ..., stopN, valueN]

to-number

Converts the value to a number. If the value cannot be converted to a number then it returns the value of the first fallback that is a number.

["to-number", value, fallback1, ..., fallbackN] // number

Example:

["to-number", 42] // returns 42
["to-number", "42"] // returns 42
["to-number", "foo", "bar", "42"] // returns 42

zoom

Gets the current zoom level.

["zoom"]

Next steps

Explore the following documents when customizing map style: