Appearances

Search Style Specification

The appearances layer property defines sets of appearance objects used to quickly change the visual styling of a layer based on a condition. Each appearance object can specify a set of paint and layout property values, allowing for dynamic styling of layers based on application state or user interactions.

{
  "id": "some-layer",
  "type": "symbol",
  ...
  "appearances": [
    {
      "name": "selected",
      "condition": ["feature-state", "select"],
      "properties": {
        "icon-image": ["image", "poi", {"params": {"fill": "red"}}],
        "icon-size": 1.3,
        "text-color": "#ff0000",
        "text-halo-color": "#c0caff",
      }
    },
    {
      "name": "highlighted",
      "condition": ["feature-state", "highlighted"],
      "properties": {
        "icon-size": 2,
        "text-color": "#4264fb",
        "text-halo-color": "#c0caff",
      }
    }
  ]
}

Layout properties compatible with appearances

icon-image

Layout property. Optional resolvedImage . paletteWorks with appearances.

Name of image in sprite to use for drawing an image background.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.35.0	>= 5.1.0	>= 3.6.0

icon-offset

Layout property. Optional array of numbers . Defaults to [0,0]. Requires icon-image. Supports smooth-rampinterpolateexpressions. paletteWorks with appearances.

Offset distance of icon from its anchor. Positive values indicate right and down, while negative values indicate left and up. Each component is multiplied by the value of icon-size to obtain the final offset in pixels. When combined with icon-rotate the offset will be as if the rotated direction was up.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.29.0	>= 5.0.0	>= 3.5.0

icon-rotate

Layout property. Optional number . Units in degrees. Defaults to 0. Requires icon-image. Supports smooth-rampinterpolateexpressions. paletteWorks with appearances.

Rotates the icon clockwise.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.21.0	>= 5.0.0	>= 3.5.0

icon-size

Layout property. Optional number greater than or equal to 0. Units in factor of the original icon size. Defaults to 1. Requires icon-image. Supports smooth-rampinterpolateexpressions. paletteWorks with appearances.

Scales the original size of the icon by the provided factor. The new pixel size of the image will be the original pixel size multiplied by icon-size. 1 is the original size; 3 triples the size of the image.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.35.0	>= 5.1.0	>= 3.6.0

text-offset

Layout property. Optional array of numbers . Units in ems. Defaults to [0,0]. Requires text-field. Disabled by text-radial-offset. Supports smooth-rampinterpolateexpressions. paletteWorks with appearances.

Offset distance of text from its anchor. Positive values indicate right and down, while negative values indicate left and up. If used with text-variable-anchor, input values will be taken as absolute values. Offsets along the x- and y-axis will be applied automatically based on the anchor position.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.35.0	>= 5.1.0	>= 3.6.0

text-rotate

Layout property. Optional number . Units in degrees. Defaults to 0. Requires text-field. Supports smooth-rampinterpolateexpressions. paletteWorks with appearances.

Rotates the text clockwise.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.35.0	>= 5.1.0	>= 3.6.0

text-size

Layout property. Optional number greater than or equal to 0. Units in pixels. Defaults to 16. Requires text-field. Supports smooth-rampinterpolateexpressions. paletteWorks with appearances.

Font size.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.35.0	>= 5.1.0	>= 3.6.0

Paint properties compatible with appearances

icon-color

Paint property. Optional color . Defaults to "#000000". Requires icon-image. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

The color of the icon. This can only be used with SDF icons.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.33.0	>= 5.0.0	>= 3.5.0

icon-emissive-strength

Paint property. Optional number greater than or equal to 0. Units in intensity. Defaults to 1. Requires lights. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

Controls the intensity of light emitted on the source features.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 3.0.0	>= 11.0.0	>= 11.0.0
data-driven styling	>= 3.0.0	>= 11.0.0	>= 11.0.0

icon-halo-blur

Paint property. Optional number greater than or equal to 0. Units in pixels. Defaults to 0. Requires icon-image. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

Fade out the halo towards the outside.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.33.0	>= 5.0.0	>= 3.5.0

icon-halo-color

Paint property. Optional color . Defaults to "rgba(0, 0, 0, 0)". Requires icon-image. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

The color of the icon's halo. Icon halos can only be used with SDF icons.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.33.0	>= 5.0.0	>= 3.5.0

icon-halo-width

Paint property. Optional number greater than or equal to 0. Units in pixels. Defaults to 0. Requires icon-image. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

Distance of halo to the icon outline.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.33.0	>= 5.0.0	>= 3.5.0

icon-occlusion-opacity

Paint property. Optional number between 0 and 1 inclusive. Defaults to 0. Requires icon-image. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

The opacity at which the icon will be drawn in case of being depth occluded. Absent value means full occlusion against terrain only.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 3.5.0	>= 11.5.0	>= 11.6.0
data-driven styling	>= 3.5.0	>= 11.5.0	>= 11.6.0

icon-opacity

Paint property. Optional number between 0 and 1 inclusive. Defaults to 1. Requires icon-image. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

The opacity at which the icon will be drawn.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.33.0	>= 5.0.0	>= 3.5.0

icon-translate

Paint property. Optional array of numbers . Units in pixels. Defaults to [0,0]. Requires icon-image. Supports smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

Distance that the icon's anchor is moved from its original placement. Positive values indicate right and down, while negative values indicate left and up.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0

symbol-z-offset

EXPERIMENTAL

Paint property. Optional number greater than or equal to 0. Defaults to 0. Requires symbol-z-elevate to be true. Supports smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

Specifies an uniform elevation from the ground, in meters.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 3.7.0	>= 11.7.0	>= 11.7.0
data-driven styling	>= 3.7.0	>= 11.7.0	>= 11.7.0

text-color

Paint property. Optional color . Defaults to "#000000". Requires text-field. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

The color with which the text will be drawn.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.33.0	>= 5.0.0	>= 3.5.0

text-emissive-strength

Paint property. Optional number greater than or equal to 0. Units in intensity. Defaults to 1. Requires lights. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

Controls the intensity of light emitted on the source features.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 3.0.0	>= 11.0.0	>= 11.0.0
data-driven styling	>= 3.0.0	>= 11.0.0	>= 11.0.0

text-halo-blur

Paint property. Optional number greater than or equal to 0. Units in pixels. Defaults to 0. Requires text-field. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

The halo's fadeout distance towards the outside.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.33.0	>= 5.0.0	>= 3.5.0

text-halo-color

Paint property. Optional color . Defaults to "rgba(0, 0, 0, 0)". Requires text-field. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

The color of the text's halo, which helps it stand out from backgrounds.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.33.0	>= 5.0.0	>= 3.5.0

text-halo-width

Paint property. Optional number greater than or equal to 0. Units in pixels. Defaults to 0. Requires text-field. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

Distance of halo to the font outline. Max text halo width is 1/4 of the font-size.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.33.0	>= 5.0.0	>= 3.5.0

text-occlusion-opacity

Paint property. Optional number between 0 and 1 inclusive. Defaults to 0. Requires text-field. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

The opacity at which the text will be drawn in case of being depth occluded. Absent value means full occlusion against terrain only.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 3.5.0	>= 11.5.0	>= 11.6.0
data-driven styling	>= 3.5.0	>= 11.5.0	>= 11.6.0

text-opacity

Paint property. Optional number between 0 and 1 inclusive. Defaults to 1. Requires text-field. Supports combinefeature-state and smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

The opacity at which the text will be drawn.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0
data-driven styling	>= 0.33.0	>= 5.0.0	>= 3.5.0

text-translate

Paint property. Optional array of numbers . Units in pixels. Defaults to [0,0]. Requires text-field. Supports smooth-rampinterpolateexpressions. opacityTransitionable. paletteWorks with appearances.

Distance that the text's anchor is moved from its original placement. Positive values indicate right and down, while negative values indicate left and up.

SDK Support	Mapbox GL JS	Android SDK	iOS SDK
basic functionality	>= 0.10.0	>= 2.0.1	>= 2.0.0

Was this page helpful?