MapsGL - Expressions

MapsGL supports expressions: small programs written as JSON arrays that compute a value from feature properties, the current zoom level, and optional local variables. They follow the same general shape as Mapbox Style Spec expressions : the first element is an operator name (string), and the rest are arguments (literals or nested expressions).

["operator", argument0, argument1, ...]

Usage

Expressions are used in several places in MapsGL:

1. Layer filters — Expressions can be used to filter features in a vector layer. The expression must evaluate to a boolean. Features are kept when the result is truthy. Evaluation receives each feature’s properties plus $zoom (tile zoom as a number) so camera-aware filters work.

2. Paint and layout-style values — Many paint options accept a data-driven style value, which can be a constant, a function, e.g. (properties) => value, or an expression array. When the value is an expression, the expression will be evaluated with the feature’s properties and the result will be used as the value for the paint property.

Compatibility notes

MapsGL’s set is Mapbox-like but not identical:

• Camera — Only zoom is supported (via ["zoom"]). There is no pitch, distance-from-center, etc.
• No color-specific expression operators — No rgb, rgba, to-color, interpolate-hcl, etc.; colors are usually plain string constants, e.g. "#FF0000" or rgba(255, 0, 0, 1), or come from the style pipeline elsewhere.
• Extensions — regex, to-unit, and to-locale-string are MapsGL additions for filtering and text formatting.
• Nested property paths — Dotted property paths, e.g. "report.cat", are supported in the get expression for accessing nested properties. This avoids the need to use multiple get expressions to access nested properties.

Types and conversion

literal

Returns a literal JSON value (object, array, number, string, boolean, or null) without interpreting it as an expression. Use this when you need an array or object value as data, not as an operator list.

Format: ["literal", value]

Example:

["get", "items", ["literal", { "items": [1, 2, 3] }]]

["literal", [10, 20, 30]]

to-number

Converts arguments to a number in order; returns the first that successfully converts. If none convert, returns NaN.

Format: ["to-number", value, ...]

Example:

["to-number", ["get", "pressure_hpa"]]

["to-number", "3.14", 0]

to-string

Converts the value to a string (JavaScript String).

Format: ["to-string", value]

Example:

["to-string", ["get", "id"]]

to-locale-string

Formats a numeric value for display using Number.prototype.toLocaleString. If the value is not a number, returns String(value). Optional second argument is a BCP 47 locale (default "en-US").

Format: ["to-locale-string", value]

Format: ["to-locale-string", value, locale]

Example:

["to-locale-string", ["get", "population"]]

["to-locale-string", 1234.5, "de-DE"]

to-unit

Converts a numeric measurement from a base unit to a target unit using the shared units utilities, then returns a string fixed to the requested decimal precision. Returns null if the input is missing or not a number.

Format: ["to-unit", value, measurementType, baseUnit, toUnit]

Format: ["to-unit", value, measurementType, baseUnit, toUnit, precision]

Example:

["to-unit", ["get", "temp"], "temperature", "C", "F"]

["to-unit", 10, "speed", "m/s", "mph", 1]

to-boolean

JavaScript-style truthiness: false for "", 0, false, null, NaN; otherwise true.

Format: ["to-boolean", value]

Example:

["to-boolean", ["get", "active"]]

typeof

Returns the JavaScript typeof string for the evaluated value.

Format: ["typeof", value]

Example:

["==", ["typeof", ["get", "x"]], "number"]

number, string, boolean, object

Type assertions: each tries inputs in order and returns the first that matches the type. Throws if none match (unlike Mapbox, which often falls back to a style default).

Format: ["number", value, ...]

Format: ["string", value, ...]

Format: ["boolean", value, ...]

Format: ["object", value, ...]

Example:

["number", ["get", "count"], 0]

coalesce

Returns the first argument whose evaluated value is not null or undefined. If all are nullish, returns null.

Format: ["coalesce", value, ...]

Example:

["coalesce", ["get", "label"], ["get", "name"], "unknown"]

Feature data and camera

get

Reads a property from the feature properties object, or from an optional object expression. Supports dotted paths in the key string (for example "report.cat").

Format: ["get", key]

Format: ["get", key, objectExpression]

Example:

["get", "severity"]

["get", "nested.field", ["literal", { "nested": { "field": 1 } }]]

has

Returns whether the property key exists on the object (including when the value is undefined). Second form uses an explicit object expression.

Format: ["has", key]

Format: ["has", key, objectExpression]

Example:

["has", "priority"]

properties

Returns the full current properties object.

Format: ["properties"]

Example:

["get", "type", ["properties"]]

zoom

Returns the current zoom. Taken from properties.$zoom, then properties.zoom, then 0 if unset. Tile parsing sets $zoom on the tile zoom for filters.

Format: ["zoom"]

Example:

["<", ["zoom"], 8]

Variable binding

let

Binds names to values (evaluated in order into a copied scope), then evaluates the final expression in that scope.

Format: ["let", name1, value1, name2, value2, ..., resultExpression]

Example:

["let", "z", ["zoom"], [">=", "$z", 10]]

var

Looks up a variable in the current let scope. The name can be a string or an expression that evaluates to a string.

Format: ["var", name]

Example:

["let", "label", ["get", "name"], ["var", "label"]]

Decision and comparison

==, !=

Strict equality. Left operand: property path shorthand or full expression. Right operand: evaluated as an expression (not path shorthand).

Format: ["==", left, right]

Format: ["!=", left, right]

Example:

["==", "type", "storm"]

["==", ["get", "category"], ["get", "expected"]]

<, <=, >, >=

Ordered comparison. Operands are resolved as numbers or strings (same kind required at runtime). Left operand supports the same string path shorthand as ==.

Format: ["<", left, right] (and <=, >, >=)

Example:

["<", "level", 10]

[">=", ["get", "wind"], 40]

!

Logical negation.

Format: ["!", booleanExpression]

Example:

["!", ["has", "exclude"]]

all, any

Boolean AND / OR over any number of sub-expressions. all is true only if all are true; any is true if any is true.

Format: ["all", expr, ...]

Format: ["any", expr, ...]

Example:

["all", ["==", "class", "road"], ["<", ["zoom"], 12]]

case

Evaluates pairs [condition, output] in order; returns the first output whose condition is truthy. If none match, returns the last argument (fallback).

Format: ["case", cond1, out1, cond2, out2, ..., fallback]

Example:

["case", ["<", ["get", "temp"], 0], "cold", ["<", ["get", "temp"], 20], "cool", "warm"]

match

Compares the evaluated input to each label (single value or array of values); returns the matching output expression’s value, or the final fallback.

Format: ["match", input, label1, out1, label2, out2, ..., fallback]

Example:

["match", ["get", "kind"], "A", 1, "B", 2, 0]

["match", ["get", "code"], [10, 11], "ten-eleven", "other"]

in

If the second argument is a string, returns whether the string contains the first argument (coerced to string). If it is an array, returns whether the array includes the value (strict equality).

Format: ["in", keyword, stringOrArray]

Example:

["in", "warn", ["get", "title"]]

["in", 2, ["literal", [1, 2, 3]]]

regex

Tests the input string against a regular expression. With three arguments after the pattern: pattern, flags, input. With two: pattern, input.

Format: ["regex", pattern, input]

Format: ["regex", pattern, flags, input]

Example:

["regex", "^[A-Z]{2}$", "US"]

["regex", "wind|storm", "i", ["get", "text"]]

Lookup and strings

at

Returns array[index]. Throws if the second argument is not an array.

Format: ["at", index, array]

Example:

["at", 0, ["get", "tags"]]

index-of

indexOf on a string or array; optional third argument is the start index.

Format: ["index-of", keyword, input]

Format: ["index-of", keyword, input, fromIndex]

Example:

["index-of", "@", ["get", "user"]]

length

Length of a string or array; otherwise 0.

Format: ["length", value]

Example:

[">", ["length", ["get", "codes"]], 0]

slice

slice on a string or array; optional end index.

Format: ["slice", input, start]

Format: ["slice", input, start, end]

Example:

["slice", ["get", "code"], 0, 3]

concat

Concatenates all arguments after converting each to a string.

Format: ["concat", value, ...]

Example:

["concat", ["get", "first"], " ", ["get", "last"]]

downcase, upcase

Lowercase / uppercase conversion (Unicode-aware via JavaScript string methods).

Format: ["downcase", string]

Format: ["upcase", string]

Example:

["downcase", ["get", "name"]]

Math

Arithmetic uses JavaScript semantics.

+

Returns the sum of all inputs.

Format: ["+", arg, ...] (two or more arguments)

Example:

["+", ["get", "a"], ["get", "b"]]

-

For two inputs, returns the difference. For one input, returns the negation.

Format: ["-", a, b]

Format: ["-", a] (unary)

Example:

["-", 100, ["get", "used"]]

*, /, %, ^

Multiply, divide, modulo, power.

Format: ["*", a, b]

Format: ["/", a, b]

Format: ["%", a, b]

Format: ["^", a, b]

Example:

["*", 100, ["get", "used"]]

abs, ceil, floor, round

Format: ["abs", x] (etc.)

Example:

["abs", ["get", "value"]]

min, max

Format: ["min", x, y, ...]

Format: ["max", x, y, ...]

Example:

["min", ["get", "value"], ["get", "value2"]]

sqrt, ln, log2, log10

Format: ["sqrt", x] (etc.)

Example:

["sqrt", ["get", "value"]]

sin, cos, tan, asin, acos, atan

Trigonometric functions; angles in radians.

Example:

["sin", ["get", "value"]]

e, pi, ln2

Constants: Math.E, Math.PI, Math.LN2.

Format: ["e"]

Format: ["pi"]

Format: ["ln2"]

Example:

["e"]

["pi"]

["ln2"]

Ramps and interpolation

step

Piecewise-constant function. Input must evaluate to a number. After input and the first output, arguments are alternating stop (numeric literal) and output (expression). Stop values must be strictly ascending. For each pair in order, if input >= stop, the result becomes that pair’s output; if input < stop, evaluation stops and the current result is used. If input is less than the first stop, the first output (the argument right after input) is used.

Format: ["step", input, output0]

Format: ["step", input, output0, stop1, output1, stop2, output2, ...]

Example:

["step", ["zoom"], 2, 5, 4, 10, 8]

With zoom 0–4 the result is 2; at 5–9 it is 4; at 10 and above it is 8.

["step", ["get", "value"], "#FF0000", 10, "#00FF00", 20, "#0000FF"]

With value 0–9 the result is #FF0000; at 10–19 it is #00FF00; at 20 and above it is #0000FF.

interpolate

Linear or exponential interpolation between stops. First argument is ["linear"] or ["exponential", base] (base defaults to 1). Second argument is the input expression. Remaining arguments are alternating stopInput (literal number) and stopOutput (expression). Behavior for inputs outside the first interval follows the implementation: interpolate when input is in [t0, t1), otherwise fall through to the last stop output value.

Format: ["interpolate", ["linear"], input, t0, v0, t1, v1, ...]

Format: ["interpolate", ["exponential", base], input, ...]

Example:

["interpolate", ["linear"], ["zoom"], 5, 1, 10, 4]

["interpolate", ["exponential", 1.5], ["get", "population"], 0, 0, 1000000, 1]

Quick reference (operator names)