Expressions

MapLibre expressions provide a powerful way to dynamically style map features based on their properties and zoom level. Expressions use a JSON array format to define operations that can manipulate data, perform calculations, and apply conditional logic.

1. Expression Types & Syntax 📝

Expression Syntax

Expressions are represented as JSON arrays where the first element is a string naming the expression operator, and subsequent elements are the arguments to the operator.

Basic Syntax

[expression_name, argument_0, argument_1, ...]

Types of Expressions

  • Data expressions: Access feature properties ["get", "propertyName"]
  • Camera expressions: Access zoom level ["zoom"]
  • Composition expressions: Combine multiple expressions
  • Type expressions: Assert or convert data types
  • Math expressions: Perform mathematical operations
  • String expressions: Manipulate text data
  • Boolean expressions: Evaluate logical conditions

2. Data Expressions & Feature Properties 📊

get
data expression
["get", string]
["get", string, object]

Retrieves a property value from the current feature's properties. If the property is missing, returns the optional default value.

property string The name of the property to retrieve
default any (optional) Value to return if the property is missing
Returns: any (The property value)

Usage Example: Accessing Feature Properties

// Get the 'name' property from a feature
"text-field": ["get", "name"],

// Get 'population' with a default of 0
"text-size": ["get", "population", 0]
has
data expression
["has", string]

Returns true if the specified property exists in the current feature's properties, false otherwise.

property string The name of the property to check
Returns: boolean

Usage Example: Checking Property Existence

// Only show label if feature has a 'name' property
"text-field": [
  "case",
  ["has", "name"],
  ["get", "name"],
  ""
]
properties
data expression
["properties"]

Returns the entire properties object of the current feature.

Returns: object

Usage Example: Accessing All Properties

// This expression itself doesn't do much, but can be useful
// in combination with other expressions
"text-field": ["get", "name"] // Better to use ["get", "name"] directly

3. Camera Expressions & Zoom Levels 🎥

zoom
camera expression
["zoom"]

Returns the current zoom level. Useful for creating zoom-dependent styling.

Returns: number (Current zoom level)

Usage Example: Zoom-Dependent Styling

// Increase circle radius at higher zoom levels
"circle-radius": [
  "interpolate",
  ["linear"],
  ["zoom"],
  0, 1,
  10, 5,
  20, 15
]
interpolate
camera expression
["interpolate", interpolation, number, number, number, ...]

Produces continuous, smooth results by interpolating between pairs of input and output values.

interpolation expression The interpolation type: ["linear"], ["exponential", base], or ["cubic-bezier", x1, y1, x2, y2]
input number The input value expression (e.g., ["zoom"])
stop_input number Input value at which the output should be stop_output
stop_output number Output value when input is stop_input
Additional stop_input/stop_output pairs
Returns: number (Interpolated value)

Usage Example: Smooth Zoom Interpolation

// Line width increases with zoom level
"line-width": [
  "interpolate",
  ["linear"],
  ["zoom"],
  0, 1,
  10, 2,
  15, 4,
  20, 8
]
step
camera expression
["step", input, output0, stop1, output1, stop2, output2, ...]

Produces discrete results by evaluating a piecewise-constant function defined by stops.

input number The input value expression (e.g., ["zoom"])
output0 any Default output value when input < stop1
stopN number Input threshold value
outputN any Output value when input >= stopN
Returns: any (Step-based output)

Usage Example: Discrete Zoom-Based Changes

// Change icon size at specific zoom levels
"icon-size": [
  "step",
  ["zoom"],
  0.5,
  10, 1,
  15, 1.5,
  20, 2
]

4. Composition Expressions 🧩

let
composition expression
["let", string, any, string, any, ..., expression]

Binds values to named variables, which can then be referenced in the result expression.

bindings pairs of string, any Variable name and value pairs
result expression Expression that uses the bound variables
Returns: any (Result of the final expression)

Usage Example: Variable Binding

// Calculate area and use it in multiple places
"text-field": [
  "let", "area", ["/", ["get", "sq_meters"], 1000000],
  ["concat", "Area: ", ["to-string", ["var", "area"]], " km²"]
]
var
composition expression
["var", string]

References a variable bound in the current scope using the "let" expression.

name string The name of the variable to reference
Returns: any (The variable's value)

Usage Example: Using Bound Variables

// Using variables for complex calculations
"circle-radius": [
  "let", "population", ["get", "population"],
  "let", "scaled", ["/", ["var", "population"], 1000],
  ["sqrt", ["var", "scaled"]]
]

5. Type Expressions 🔧

array
type expression
["array", valueType, value]

["array", valueType]

Asserts that the input is an array of the specified value type. If the input is null or not an array, returns the provided default value or null.

valueType string The expected type of array elements: "number", "string", or "boolean"
value any The value to assert as an array
Returns: array (The input as an array)

Usage Example: Type Assertion

// Ensure coordinates is treated as an array
"circle-radius": [
  "case",
  [">", ["length", ["array", "number", ["get", "coordinates"]]], 0],
  5,
  0
]
to-string
type expression
["to-string", value]

Converts the input value to a string. If the input is null, returns null.

value any The value to convert to string
Returns: string

Usage Example: String Conversion

// Convert numeric population to string for display
"text-field": [
  "concat",
  "Population: ",
  ["to-string", ["get", "population"]]
]
to-number
type expression
["to-number", value]
["to-number", value, fallback]

Converts the input value to a number, if possible. If conversion fails, returns the fallback value or null.

value any The value to convert to number
fallback number (optional) Value to return if conversion fails
Returns: number

Usage Example: Numeric Conversion

// Safely convert string property to number
"circle-radius": [
  "to-number",
  ["get", "radius"],
  5 // default if conversion fails
]

6. Math Expressions ➗

+
math expression
["+", number, number, ...]

Returns the sum of the inputs.

numbers number Numbers to add together
Returns: number (Sum of inputs)

Usage Example: Addition

// Add a buffer to a base value
"circle-radius": ["+", ["get", "base_radius"], 2]
-
math expression
["-", number, number]
["-", number]

For two inputs, returns the result of subtracting the second input from the first. For one input, returns the negation of the input.

numbers number Numbers to subtract
Returns: number (Difference or negation)

Usage Example: Subtraction

// Calculate difference between values
"text-field": [
  "concat",
  "Diff: ",
  ["to-string", ["-", ["get", "current"], ["get", "previous"]]]
]
sqrt
math expression
["sqrt", number]

Returns the square root of the input number.

number number The number to calculate square root of
Returns: number (Square root)

Usage Example: Square Root Calculation

// Scale circle radius by square root of population
"circle-radius": [
  "sqrt",
  ["/", ["get", "population"], 1000]
]
^
math expression
["^", number, number]

Returns the result of raising the first number to the power of the second number.

base number The base number
exponent number The exponent
Returns: number (Base raised to exponent)

Usage Example: Power Calculation

// Exponential scaling
"circle-radius": ["^", 2, ["get", "scale_factor"]]

7. String Expressions 🔤

concat
string expression
["concat", value, value, ...]

Returns a string consisting of the concatenation of the inputs. Non-string values will be converted to strings.

values any Values to concatenate
Returns: string (Concatenated result)

Usage Example: String Concatenation

// Create a formatted label
"text-field": [
  "concat",
  ["get", "name"],
  " (",
  ["to-string", ["get", "population"]],
  ")"
]
upcase
string expression
["upcase", string]

Returns the input string converted to uppercase.

string string The string to convert to uppercase
Returns: string (Uppercase string)

Usage Example: Uppercase Conversion

// Display name in uppercase
"text-field": ["upcase", ["get", "name"]]
downcase
string expression
["downcase", string]

Returns the input string converted to lowercase.

string string The string to convert to lowercase
Returns: string (Lowercase string)

Usage Example: Lowercase Conversion

// Display category in lowercase
"text-field": ["downcase", ["get", "category"]]

8. Boolean Expressions & Logic 🧠

case
boolean expression
["case", condition1, output1, condition2, output2, ..., fallback]

Selects the first output whose corresponding condition evaluates to true.

conditions boolean Boolean expressions to evaluate
outputs any Output values for corresponding conditions
fallback any Default output if no conditions are true
Returns: any (Selected output)

Usage Example: Conditional Styling

// Color code based on category
"circle-color": [
  "case",
  ["==", ["get", "category"], "school"], "#ff0000",
  ["==", ["get", "category"], "hospital"], "#00ff00",
  ["==", ["get", "category"], "park"], "#0000ff",
  "#cccccc" // default color
]
match
boolean expression
["match", input, label1, output1, label2, output2, ..., fallback]

Selects the output whose label value matches the input, or the fallback if no match is found.

input any The value to match against labels
labels any Values to compare with input
outputs any Output values for matching labels
fallback any Default output if no match is found
Returns: any (Matched output)

Usage Example: Value Matching

// Match category to specific colors
"circle-color": [
  "match",
  ["get", "category"],
  "school", "#ff0000",
  "hospital", "#00ff00",
  "park", "#0000ff",
  "#cccccc" // default color
]
coalesce
boolean expression
["coalesce", expression1, expression2, ...]

Evaluates each expression in order until the first non-null value is obtained, and returns that value.

expressions any Expressions to evaluate in order
Returns: any (First non-null value)

Usage Example: Fallback Values

// Try multiple property names for label
"text-field": [
  "coalesce",
  ["get", "name"],
  ["get", "title"],
  ["get", "id"],
  "Unknown"
]