Types
A Mapbox 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. Format options are listed in the documentation for the format expression.
{
"text-field": ["format",
"foo", { "font-scale": 1.2 },
"bar", { "font-scale": 0.8 }
]
}
ResolvedImage
The ResolvedImage type is an image (for example, an icon or pattern) that 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. To define a series of images that the map can fall back to if previous images are not found, you can wrap ResolvedImage expressions in a coalesce expression.
If a ResolvedImage with no matching image in the style is passed to an image property, the map throws a styleimagemissing event.
{
"icon-image": ["coalesce", ["image", "myImage"], ["image", "fallbackImage"]]
}
ImageOptions
The ImageOptions type is an object that contains options for an image. The options are used to specify how the vector image is rendered on the map. The options are passed as the next argument after the image name in the image expression operator.
{
params: {
background: "#000000",
main: ["get", "main_color"]
...
}
}
The params field contains dictionary of colors that are used to replace the colors in the image. The keys are the color names in the vector image and the values have the type of color. Values of that dictionary will be used to replace corresponding colors by values (or evaluation results in case of an expression). Unknown color names are ignored and error messages are logged to the console. Colors can be specified in the uploaded to the Mapbox Studio SVG file as the following:
<svg xmlns="http://www.w3.org/2000/svg" xmlns:m="https://www.mapbox.com">
<m:metadata>
<m:parameters>
<m:parameter m:name="background" m:type="color" m:value="#ffffff" />
<m:parameter m:name="main" m:type="color" m:value="#ff0000" />
</m:parameters>
</m:metadata>
...
<!-- "background" color usage -->
<rect fill="#ffffff">
<!-- "main" color usage -->
<circle fill="#ff0000">
</rect>
</svg>
String
A string is text. In Mapbox 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]]]
}