Types

A GL style contains values of various types, most commonly as values for the style properties of a layer.

Color

The color type is a color in the sRGB color space. Colors are JSON strings in a variety of permitted formats: HTML-style hex values, RGB, RGBA, HSL, and HSLA. Predefined HTML colors names, like yellow and blue, are also permitted.

{
    "line-color": "#ff0",
    "line-color": "#ffff00",
    "line-color": "rgb(255, 255, 0)",
    "line-color": "rgba(255, 255, 0, 1)",
    "line-color": "hsl(100, 50%, 50%)",
    "line-color": "hsla(100, 50%, 50%, 1)",
    "line-color": "yellow"
}

Especially of note is the support for HSL, which can be easier to reason about than RGB.

Formatted

The formatted type is a string broken into sections annotated with separate formatting options.

{
    "text-field": ["format",
        "foo", { "font-scale": 1.2 },
        "bar", { "font-scale": 0.8 }
    ]
}

ResolvedImage

The resolvedImage type is an image (e.g., an icon or pattern) which is used in a layer. An input to the image expression operator is checked against the current map style to see if it is available to be rendered or not, and the result is returned in the resolvedImage type. This approach allows developers to define a series of images which the map can fall back to if previous images are not found, which cannot be achieved by providing, for example, icon-image with a plain string (because multiple strings cannot be supplied to icon-image and multiple images cannot be defined in a string).

{
    "icon-image": ["coalesce", ["image", "myImage"], ["image", "fallbackImage"]]
}

String

A string is text. In GL styles, strings are in quotes.

{
    "source": "mySource"
}

Boolean

Boolean means yes or no, so it accepts the values true or false.

{
    "fill-enabled": true
}

Number

A number value, often an integer or floating point (decimal number). Written without quotes.

{
    "text-size": 24
}

Array

Arrays are comma-separated lists of one or more numbers in a specific order. For example, they’re used in line dash arrays, in which the numbers specify intervals of line, break, and line again. If an array is used as an argument in an expression, the array must be wrapped in a literal expression.

{
    "line-dasharray": [2, 4]
}

{
    "circle-color": ["in", 1, ["literal", [1, 2, 3]]]
}

Enum

An Enum is a special data type that enables for a variable to be a set of predefined constants. The variable must be equal to one of the values that have been predefined for it.

{
    "scheme": "tms"
}

{
    "encoding": "terrarium"
}

Look at the allowed values in the attribute definition. Ex. raster-dem encoding

PromoteId

A property to use as a feature id (for feature state). Either a property name, or an object of the form {<sourceLayer>: <propertyName>}. If specified as a string for a vector tile source, the same property is used across all its source layers.

ProjectionDefinition

The projection is used to configure which projection to use for the map.

There are currently two projections implemented.

• mercator - Web Mercator projection
• vertical-perspective - Vertical Perspective projection

And the following presets

The projection output sent to the renderer is always of the shape:

[from, to, transition]: [string, string, number]

• from is the projection of lower zoom level
• to is the projection of higher zoom level
• transition is the interpolation value, going from 0 to 1, with 0 being in the from projection, and 1 being in the to projection.

In case from and to are equal, the transition will have no effect.

Step between projection at discrete zoom levels

Use a camera expression, to discretely step between projections at certain zoom levels.

type: ["step", ["zoom"],
    "vertical-perspective",
    11, "mercator"
]


output at zoom 10.9: "vertical-perspective"
output at zoom 11.0: "vertical-perspective"
output at zoom 11.1: "mercator"

Animate between different projections based on zoom level

Use a camera expression, to animate between projections based on zoom, using interpolate function. The example below will yield an adaptive globe that interpolates from vertical-perspective to mercator between zoom 10 and 12.

type: ["interpolate", ["linear"], ["zoom"],
    10,"vertical-perspective",
    12,"mercator"
]


output at zoom 9.9:  "vertical-perspective"
output at zoom 11:   ["vertical-perspective", "mercator", 0.5]
output at zoom 12:   ["vertical-perspective", "mercator", 1]
output at zoom 12.1: "mercator"

Provide a projection

type: ["vertical-perspective", "mercator", 0.7]

Use a projection preset

There are also additional presets that yield commonly used expressions: