> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/style-spec/llms.txt)
# Types
A Mapbox style contains values of various types, most commonly as values for the style properties of a layer.
## Appearance
Appearances are objects containing paint and layout properties and conditions for when those properties should be used. They are used for defining multiple appearances for a single layer, such as for different feature states.
```json
{
"name": "selected",
"condition": ["feature-state", "select"],
"properties": {
"icon-image": ["image", "poi", {"params": {"fill": "red"}}],
"icon-size": 1.3
}
}
{
"name": "highlighted",
"condition": ["feature-state", "highlighted"],
"properties": {
"icon-rotate": 90
}
}
```
### condition
Optional [boolean](https://docs.mapbox.com/style-spec/reference/types/#boolean) . Supports *[`feature-state`](https://docs.mapbox.com/style-spec/reference/expressions/#feature-state)* and [`interpolate`](https://docs.mapbox.com/style-spec/reference/expressions/#interpolate)expressions.
A boolean expression that determines when this appearance should be applied.
### name
Optional [string](https://docs.mapbox.com/style-spec/reference/types/#string) .
Optional name for this appearance. Non-empty names should be unique within a layer.
### properties
Optional * .
Style properties to apply when the condition is met.
## 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.
```json
{
"line-dasharray": [2, 4]
}
{
"circle-color": ["in", 1, ["literal", [1, 2, 3]]]
}
```
## Boolean
Boolean means yes or no, so it accepts the values `true` or `false`.
```json
{
"fill-enabled": true
}
```
## Camera
An object to control additional camera intrinsic parameters for the map.
```json
{
"camera": {
"camera-projection": "orthographic",
}
}
```
### camera-projection
Optional [enum](https://docs.mapbox.com/style-spec/reference/types/#enum) . One of `"perspective"`, `"orthographic"`. Defaults to `"perspective"`.
Camera projection describes how 3D world geometry get projected into 2D screen
`"perspective"`:
linear projection where distant objects appear smaller than closer objects. Lines that are parallel seem to converge towards a vanishing point
`"orthographic"`:
Projection where objects are of the same scale regardless of whether they are far away or near to the camera. Parallel lines remains parallel and there is no vanishing point.
| SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
| --- | --- | --- | --- |
| basic functionality | >= 3.0.0 | >= 11.0.0 | >= 11.0.0 |
## Color
A color in the [sRGB color space](https://en.wikipedia.org/wiki/SRGB). 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.
```json
{
"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](http://mothereffinghsl.com/).
## ColorTheme
An object defining a lookup table (LUT) for use in modifying the colors of the map.
```json
{
"color-theme": {
"data": "VElUTEUgIlNhbXBsZSBMVVQiCkxVVF8zRF9TS..."
}
}
```
### data
Optional [string](https://docs.mapbox.com/style-spec/reference/types/#string) .
Expects a base64 encoded PNG image which represents a cube strip LUT. The height of the image cannot exceed 32 pixels and the width must be equal to the height squared.
## Enum
An enum is a type that can have one of a fixed set of values. For example, the `line-cap` property supports `butt`, `round`, or `square`.
```json
{
"line-cap": "round"
}
```
## Featuresets
An object that defines sets of features for querying, interaction, and state management on the map, referencing individual layers or subsets of layers within the map's style.
```json
{
"featuresets": {
"poi": {
"selectors": [
{
"layer": "poi",
"properties": {
"type": ["get", "type"],
"name": ["get", "name"],
"brand": "ABC"
}
}
]
}
}
}
```
## Formatted
A string broken into sections annotated with separate formatting options. Format options are listed in the documentation for the [format](https://docs.mapbox.com/style-spec/reference/expressions#types-format) expression.
```json
{
"text-field": ["format",
"foo", { "font-scale": 1.2 },
"bar", { "font-scale": 0.8 }
]
}
```
## Iconsets
Defines icon sets to include in the style. Icon sets can be used to define multiple sprite sheets where icons can be requested from instead of relying on the single sprite definition in the style. It can be either a `sprite` icon set, which must provide a URL or a `source` icon set, which must provide a source name.
```json
{
iconsets: {
"spriteIconset": {
type: 'sprite',
url: 'myURL'
},
"sourceIconset". {
type: 'source',
source: 'mySource'
}
}
}
```
## ImageOptions
An object that contains options for an image. Both the `params` and `iconset` keys are optional. The options are passed as the next argument after the image name in the [`image`](https://docs.mapbox.com/style-spec/reference/expressions#types-image) expression operator.
```json
"icon-image": [
"image",
"oval",
// ImageOptions object
{
"params": {
"background": "#000000",
"main": ["get", "main_color"]
...
},
"iconset": {
"id": "some-iconset"
}
}
]
```
### `params`
The `params` key contains an object of colors that are used to replace the colors in the image. The keys are the color name parameters specified in the vector image and the values are either [`Color`](#color) or an expression that evaluates to a `Color` used to replace the corresponding colors when the image is rendered. Unknown color names are ignored and error messages are logged to the console.
Color parameters can be specified in an SVG file uploaded to [Mapbox Studio](https://docs.mapbox.com/studio-manual/):
```xml
```
> **Related content (guide): [SVG Icon Custom Metadata](null)**
>
> See the full guide on adding custom metadata to SVG icons. Color names for use in the `params` object must be defined in the SVG file metadata.
### `iconset`
The `iconset` key specifies the icon set to use when looking up the image, useful for preventing name collisions between images with the same id from different iconsets.
## Models
An object of the form `{: }` that specifies the location of 3D models to be used in the map.
```json
{
"models": {
"spruce1-lod0": "mapbox://models/mapbox/spruce1-lod0.glb",
"spruce1-lod1": "http://somedomain.com/models/spruce1-lod1.glb",
"spruce1-lod2": "https://somedomain.com/models/spruce1-lod2.glb"
}
}
```
## Model Source Models
An object to control additional camera intrinsic parameters for the map.
```json
{
"sources" : {
"3d-model-source": {
"type": "model",
"models": {
"car-model-1": {
"uri": "/assets/car1.glb",
"orientation": [0, 45, 0],
"materialOverrides": {
"car_body_paint" : {
// ....
}
}
// ...
},
"car-model-2": {
"uri": "/assets/car2.glb",
// ...
}
}
}
}
}
```
### uri
Required [string](https://docs.mapbox.com/style-spec/reference/types/#string) .
A URL to a model resource. Supported protocols are `http:`, `https:`, and `mapbox://`.
### featureProperties
Optional * .
An object defining custom properties of the model. Properties are accessible as feature properties in expressions.
### lightOverrides
Optional [modelLightOverrides](https://docs.mapbox.com/style-spec/reference/types/#modelLightOverrides) .
A collection of light overrides.
### materialOverrideNames
Optional [array](https://docs.mapbox.com/style-spec/reference/types/#array) of [strings](https://docs.mapbox.com/style-spec/reference/types/#string) .
An array of one or more model material names whose properties will be overridden from model layer paint properties.
### materialOverrides
Optional [modelMaterialOverrides](https://docs.mapbox.com/style-spec/reference/types/#modelMaterialOverrides) .
A collection of material overrides.
### nodeOverrideNames
Optional [array](https://docs.mapbox.com/style-spec/reference/types/#array) of [strings](https://docs.mapbox.com/style-spec/reference/types/#string) .
An array of one or more model node names whose transform will be overridden from model layer paint properties.
### nodeOverrides
Optional [modelNodeOverrides](https://docs.mapbox.com/style-spec/reference/types/#modelNodeOverrides) .
A collection of node overrides.
### orientation
Optional [array](https://docs.mapbox.com/style-spec/reference/types/#array) of [numbers](https://docs.mapbox.com/style-spec/reference/types/#number) . Units in degrees. Defaults to `[0,0,0]`.
Orientation of the model in euler angles [x, y, z].
### position
Optional [array](https://docs.mapbox.com/style-spec/reference/types/#array) of [numbers](https://docs.mapbox.com/style-spec/reference/types/#number) [ between `-180` and `180` inclusive, between `-90` and `90` inclusive ]. Defaults to `[0,0]`.
Position of the model in longitude and latitude [lng, lat].
## Model Light Overrides
Override lighting properties applied to an individual 3D model.
```json
{
"lightOverrides": {
"light-ambient-color": "rgb(255, 255, 255)",
"light-ambient-intensity": 0.5,
"light-directional-color": "rgb(255, 255, 255)",
"light-directional-intensity": 0.5
}
}
```
### light-ambient-color
Optional [color](https://docs.mapbox.com/style-spec/reference/types/#color) .
Override the color of ambient lights.
### light-ambient-intensity
Optional [number](https://docs.mapbox.com/style-spec/reference/types/#number) .
Override the intensity of light-ambient-color (on a scale from 0 to 1).
### light-directional-color
Optional [color](https://docs.mapbox.com/style-spec/reference/types/#color) .
Override the color of directional lights.
### light-directional-intensity
Optional [number](https://docs.mapbox.com/style-spec/reference/types/#number) .
Override the intensity of light-directional-color (on a scale from 0 to 1).
## Model Material Overrides
Override properties of an individual material within a 3D model. The key is a material name from the `GLTF` model, and the corresponding value defines the override properties for that material.
```json
{
"material_1_name": {
"model-color" : "rgb(255, 255, 0)",
"model-opacity" : 0.5
...
},
"material_2_name": {
...
"model-emissive-strength": 0.4
}
}
```
### model-color
Optional [color](https://docs.mapbox.com/style-spec/reference/types/#color) .
Override the tint color of the material.
### model-color-mix-intensity
Optional [number](https://docs.mapbox.com/style-spec/reference/types/#number) .
Override the intensity of model-color (on a scale from 0 to 1) in color mix with original 3D model's colors.
### model-emissive-strength
Optional [number](https://docs.mapbox.com/style-spec/reference/types/#number) . Units in intensity.
Override strength of the emission of material.
### model-opacity
Optional [number](https://docs.mapbox.com/style-spec/reference/types/#number) .
Override the opacity of the material.
## Model Node Overrides
Override transform of a node within a 3D model. The key is a node name from the 3D model, and the corresponding value defines the override properties for that node.
```json
{
"left_door": {
"model-orientation": [0,0,-15]
},
"trunk": {
"model-orientation": [15,0,0]
}
}
```
### orientation
Optional [array](https://docs.mapbox.com/style-spec/reference/types/#array) of [numbers](https://docs.mapbox.com/style-spec/reference/types/#number) . Units in degrees. Defaults to `[0,0,0]`.
Override the orientation of the model node in euler angles [x, y, z].
## Number
A number value, often an integer or floating point (decimal number). Written without quotes.
```json
{
"text-size": 24
}
```
## PromoteId
A property present in all features in a `vector` or `geojson` source to use as a feature id (for feature state). Either a property name, or an object of the form `{: }`. If specified as a string for a vector tile source, the same property is used across all its source layers. If specified as an object only specified source layers will have id overridden, others will fallback to original feature id.
```json
{
"promoteId": "some_property"
}
{
"promoteId: {
"sourceLayer": "layer_name",
"id": "some_property"
}
}
```
## ResolvedImage
An image (for example, an icon or pattern) that is used in a layer. An input to the [`image`](https://docs.mapbox.com/style-spec/reference/expressions#types-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`](https://docs.mapbox.com/style-spec/reference/expressions#coalesce) expression. If a `ResolvedImage` with no matching image in the style is passed to an image property, the map throws a [`styleimagemissing`](https://docs.mapbox.com/mapbox-gl-js/api/map/#map.event:styleimagemissing) event.
```json
{
"icon-image": ["coalesce", ["image", "myImage"], ["image", "fallbackImage"]]
}
```
## String
A string is text. In Mapbox styles, strings are in quotes.
```json
{
"source": "mySource"
}
```