Symbol
An icon or a text label.
Paint Property
icon-color
The color of the icon. This can only be used with SDF icons.
hex values, RGB, RGBA, HSL, HSLA, Colors Name
#000000
icon-halo-blur
Fade out the halo towards the outside.
number
0
icon-halo-color
The color of the icon. This can only be used with SDF icons.
hex values, RGB, RGBA, HSL, HSLA, Colors Name
#000000
icon-halo-width
Distance of halo to the icon outline.
number
0
icon-opacity
The opacity at which the icon will be drawn.
Requires : icon-image.
between 0 and 1 inclusive.
number
1
icon-translate
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.
Requires icon-image.
array of numbers
[0, 0]
icon-translate-anchor
Controls the frame of reference for icon-translate.
"map":
Icons are translated relative to the map.
"viewport":
Icons are translated relative to the viewport. Requires : icon-image. Requires : icon-translate.
string
map
text-color
The color with which the text will be drawn.
Requires text-field.
hex values, RGB, RGBA, HSL, HSLA, Colors Name
#000000
text-halo-blur
The halo's fadeout distance towards the outside.
Requires text-field.
number
0
text-halo-color
The color of the text's halo, which helps it stand out from backgrounds.
Requires text-field.
hex values, RGB, RGBA, HSL, HSLA, Colors Name
rgba(0, 0, 0, 0)
text-halo-width
Distance of halo to the font outline. Max text halo width is 1/4 of the font-size.
Requires text-field.
number
0
text-opacity
The opacity at which the text will be drawn.
Requires text-field.
between 0 and 1 inclusive.
number
1
text-translate
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.
Requires text-field.
array of numbers
[0, 0]
text-translate-anchor
Controls the frame of reference for text-translate.
"map":
The text is translated relative to the map.
"viewport":
The text is translated relative to the viewport. Requires text-field. Requires text-translate.
string
map
Layout Property
visibility
Whether this layer is displayed.
"visible":
The layer is shown.
"none":
The layer is not shown.
String( visible or none)
visible
icon-allow-overlap
If true, the icon will be visible even if it collides with other previously drawn symbols.
boolean
false
icon-anchor
Part of the icon placed closest to the anchor.
"center":
The center of the icon is placed closest to the anchor.
"left":
The left side of the icon is placed closest to the anchor.
"right":
The right side of the icon is placed closest to the anchor.
"top":
The top of the icon is placed closest to the anchor.
"bottom":
The bottom of the icon is placed closest to the anchor.
"top-left":
The top left corner of the icon is placed closest to the anchor.
"top-right":
The top right corner of the icon is placed closest to the anchor.
"bottom-left":
The bottom left corner of the icon is placed closest to the anchor.
"bottom-right":
The bottom right corner of the icon is placed closest to the anchor.
string
center
icon-ignore-placement
If true, other symbols can be visible even if they collide with the icon.
boolean
false
icon-image
Name of image in sprite to use for drawing an image background.
array of string or string ['get', 'imagename'] or 'imagename'
null
icon-keep-upright
If true, the icon may be flipped to prevent it from being rendered upside-down.
Requires : icon-image.
Requires : icon-rotation-alignment to be "map". Requires : symbol-placement to be "line", or "line-center".
boolean
false
icon-offset
Offset distance of icon from its anchor.
array of numbers
[0,0]
icon-optional
If true, text will display without their corresponding icons when the icon collides with other symbols and the text does not.
Requires : icon-image. Requires : text-field.
boolean
false
icon-padding
Size of the additional area around the icon bounding box used for detecting symbol collisions.
number
2
icon-pitch-alignment
Orientation of icon when map is pitched.
"map":
The icon is aligned to the plane of the map.
"viewport":
The icon is aligned to the plane of the viewport.
"auto":
Automatically matches the value of icon-rotation-alignment.
Requires : icon-image.
string
auto
icon-rotate
Rotates the icon clockwise.
Requires : icon-image.
number
0
icon-rotation-alignment
In combination with symbol-placement, determines the rotation behavior of icons.
"map":
When symbol-placement is set to point, aligns icons east-west. When symbol-placement is set to line or line-center, aligns icon x-axes with the line.
"viewport":
Produces icons whose x-axes are aligned with the x-axis of the viewport, regardless of the value of symbol-placement.
"auto":
When symbol-placement is set to point, this is equivalent to viewport. When symbol-placement is set to line or line-center, this is equivalent to map.
string
auto
icon-size
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.
Requires : icon-image.
number
1
icon-text-fit
Scales the icon to fit around the associated text.
"none":
The icon is displayed at its intrinsic aspect ratio.
"width":
The icon is scaled in the x-dimension to fit the width of the text.
"height":
The icon is scaled in the y-dimension to fit the height of the text.
"both":
The icon is scaled in both x- and y-dimensions.
string
none
icon-text-fit-padding
Size of the additional area added to dimensions determined by icon-text-fit, in clockwise order: top, right, bottom, left.
Requires : icon-image.
Requires : text-field.
Requires : icon-text-fit
array of numbers
[0, 0, 0, 0]
symbol-avoid-edges
If true, the symbols will not cross tile edges to avoid mutual collisions.
boolean
false
symbol-placement
Label placement relative to its geometry.
"point":
The label is placed at the point where the geometry is located.
"line":
The label is placed along the line of the geometry. Can only be used on LineString and Polygon geometries.
"line-center":
The label is placed at the center of the line of the geometry. Can only be used on LineString and Polygon geometries. Note that a single feature in a vector tile may contain multiple line geometries.
string
point
symbol-spacing
Distance between two symbol anchors.
Requires : symbol-placement to be "line".
greater than or equal to 1.
number
250
symbol-z-order
Determines whether overlapping symbols in the same layer are rendered in the order that they appear in the data source or by their y-position relative to the viewport.
"auto":
Sorts symbols by symbol-sort-key if set. Otherwise, sorts symbols by their y-position relative to the viewport if icon-allow-overlap or text-allow-overlap is set to true or icon-ignore-placement or text-ignore-placement is false.
"viewport-y":
Sorts symbols by their y-position relative to the viewport if icon-allow-overlap or text-allow-overlap is set to true or icon-ignore-placement or text-ignore-placement is false.
"source":
Sorts symbols by symbol-sort-key if set. Otherwise, no sorting is applied; symbols are rendered in the same order as the source data.
string
auto
text-allow-overlap
If true, the text will be visible even if it collides with other previously drawn symbols.
Requires text-field.
boolean
false
text-anchor
Part of the text placed closest to the anchor.
"center":
The center of the text is placed closest to the anchor.
"left":
The left side of the text is placed closest to the anchor.
"right":
The right side of the text is placed closest to the anchor.
"top":
The top of the text is placed closest to the anchor.
"bottom":
The bottom of the text is placed closest to the anchor.
"top-left":
The top left corner of the text is placed closest to the anchor.
"top-right":
The top right corner of the text is placed closest to the anchor.
"bottom-left":
The bottom left corner of the text is placed closest to the anchor.
"bottom-right":
The bottom right corner of the text is placed closest to the anchor. Requires text-field. Disabled by text-variable-anchor.
string
center
text-field
Value to use for a text label. If a plain string is provided, it will be treated as a formatted with default/inherited formatting options. SDF images are not supported in formatted text and will be ignored.
array of string or string ['get', 'propertyname'] or 'propertyyname'
''
text-font
Font stack to use for displaying text.
Requires text-field.
array of string
["Open Sans Regular","Arial Unicode MS Regular"]
text-ignore-placement
If true, other symbols can be visible even if they collide with the text.
Requires text-field.
boolean
false
text-justify
Text justification options.
"auto":
The text is aligned towards the anchor position.
"left":
The text is aligned to the left.
"center":
The text is centered.
"right":
The text is aligned to the right. Requires text-field.
string
center
text-keep-upright
If true, the text may be flipped vertically to prevent it from being rendered upside-down.
Requires text-field.
Requires text-rotation-alignment to be "map". Requires symbol-placement to be "line", or "line-center".
boolean
true
text-letter-spacing
Text tracking amount.
Requires text-field.
number
0
text-line-height
Text leading value for multi-line text.
Requires text-field.
number
1.2
text-max-angle
Maximum angle change between adjacent characters.
Requires text-field.
Requires symbol-placement to be "line", or "line-center".
number
45
text-max-width
The maximum line width for text wrapping.
Requires text-field.
Requires symbol-placement to be "point".
number
10
text-offset
Offset distance of text from its anchor. Positive values indicate right and down, while negative values indicate left and up. Requires text-field. Disabled by text-radial-offset.
array of numbers
[0,0]
text-optional
If true, icons will display without their corresponding text when the text collides with other symbols and the icon does not. Requires text-field. Requires icon-image.
boolean
false
text-padding
Size of the additional area around the text bounding box used for detecting symbol collisions.
Requires text-field.
number
2
text-pitch-alignment
Orientation of text when map is pitched.
"map":
The text is aligned to the plane of the map.
"viewport":
The text is aligned to the plane of the viewport.
"auto":
Automatically matches the value of text-rotation-alignment.
string
auto
text-radial-offset
Radial offset of text, in the direction of the symbol's anchor. Useful in combination with text-variable-anchor, which defaults to using the two-dimensional text-offset if present.
Requires text-field.
number
0
text-rotate
Rotates the text clockwise.
Requires text-field.
number
0
text-rotation-alignment
In combination with symbol-placement, determines the rotation behavior of the individual glyphs forming the text.
"map":
When symbol-placement is set to point, aligns text east-west. When symbol-placement is set to line or line-center, aligns text x-axes with the line.
"viewport":
Produces glyphs whose x-axes are aligned with the x-axis of the viewport, regardless of the value of symbol-placement.
"auto":
When symbol-placement is set to point, this is equivalent to viewport. When symbol-placement is set to line or line-center, this is equivalent to map.
Requires text-field.
string
auto
text-size
Font size. Requires text-field.
number
16
text-transform
Specifies how to capitalize text, similar to the CSS text-transform property.
"none":
The text is not altered.
"uppercase":
Forces all letters to be displayed in uppercase.
"lowercase":
Forces all letters to be displayed in lowercase. Requires text-field.
string
none
text-writing-mode
The property allows control over a symbol's orientation. Note that the property values act as a hint, so that a symbol whose language doesn’t support the provided orientation will be laid out in its natural orientation.
"horizontal":
If a text's language supports horizontal writing mode, symbols would be laid out horizontally.
"vertical":
If a text's language supports vertical writing mode, symbols would be laid out vertically.
string
''
Last updated