# `` SymbolLayer is a style layer that renders icon and text labels at points or along lines on the map. ## Props | Prop | Type | Default | Required | Description | | ---- | :--: | :-----: | :------: | :----------: | | style | `SymbolLayerStyle` | `none` | `false` | Customizable style attributes | | sourceID | `FIX ME UNKNOWN TYPE` | `MLRNModule.StyleSource.DefaultSourceID` | `false` | FIX ME NO DESCRIPTION | ## Styles * `symbolPlacement`
* `symbolSpacing`
* `symbolAvoidEdges`
* `iconAllowOverlap`
* `iconIgnorePlacement`
* `iconOptional`
* `iconRotationAlignment`
* `iconSize`
* `iconImage`
* `iconRotate`
* `iconPadding`
* `iconKeepUpright`
* `iconOffset`
* `textRotationAlignment`
* `textField`
* `textFont`
* `textSize`
* `textMaxWidth`
* `textLineHeight`
* `textLetterSpacing`
* `textJustify`
* `textAnchor`
* `textMaxAngle`
* `textRotate`
* `textPadding`
* `textKeepUpright`
* `textTransform`
* `textOffset`
* `textAllowOverlap`
* `textIgnorePlacement`
* `textOptional`
* `visibility`
* `iconOpacity`
* `iconColor`
* `iconHaloColor`
* `iconHaloWidth`
* `iconHaloBlur`
* `iconTranslate`
* `iconTranslateAnchor`
* `textOpacity`
* `textColor`
* `textHaloColor`
* `textHaloWidth`
* `textHaloBlur`
* `textTranslate`
* `textTranslateAnchor`
### `symbolPlacement` Label placement relative to its geometry.

Type

enum

Default Value

point

Supported Values

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.

Expression Parameters

zoom

### `symbolSpacing` Distance between two symbol anchors.

Type: number
Default Value: 250
Units: pixels
Minimum: 1
Expression Parameters: zoom

### `symbolAvoidEdges` If true, the symbols will not cross tile edges to avoid mutual collisions. Recommended in layers that don't have enough padding in the vector tile to prevent collisions, or if it is a point symbol layer placed after a line symbol layer. When using a client that supports global collision detection, like VietMap GL JS version 0.42.0 or greater, enabling this property is not needed to prevent clipped labels at tile boundaries.

Type: boolean
Default Value: false
Expression Parameters: zoom

### `iconAllowOverlap` If true, the icon will be visible even if it collides with other previously drawn symbols.

Type: boolean
Default Value: false
Requires: iconImage
Disabled By: iconOverlap
Expression Parameters: zoom

### `iconIgnorePlacement` If true, other symbols can be visible even if they collide with the icon.

Type: boolean
Default Value: false
Requires: iconImage
Expression Parameters: zoom

### `iconOptional` If true, text will display without their corresponding icons when the icon collides with other symbols and the text does not.

Type: boolean
Default Value: false
Requires: iconImage, textField
Expression Parameters: zoom

### `iconRotationAlignment` In combination with `symbolPlacement`, determines the rotation behavior of icons.

Type

enum

Default Value

auto

Supported Values

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`.

Requires

iconImage

Expression Parameters

zoom

### `iconSize` 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 `iconSize`. 1 is the original size; 3 triples the size of the image.

Type: number
Default Value: 1
Units: factor of the original icon size
Minimum: 0
Requires: iconImage
Expression Parameters: zoom, feature

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

Type: resolvedImage
Expression Parameters: zoom, feature

### `iconRotate` Rotates the icon clockwise.

Type: number
Default Value: 0
Units: degrees
Requires: iconImage
Expression Parameters: zoom, feature

### `iconPadding` Size of additional area round the icon bounding box used for detecting symbol collisions.

Type: array
Default Value: [2]
Units: pixels
Requires: iconImage
Expression Parameters: zoom, feature

### `iconKeepUpright` If true, the icon may be flipped to prevent it from being rendered upsideDown.

Type: boolean
Default Value: false
Requires: iconImage
Expression Parameters: zoom

### `iconOffset` 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 `iconSize` to obtain the final offset in pixels. When combined with `iconRotate` the offset will be as if the rotated direction was up.

Type: array
Default Value: [0,0]
Requires: iconImage
Expression Parameters: zoom, feature

### `textRotationAlignment` In combination with `symbolPlacement`, determines the rotation behavior of the individual glyphs forming the text.

Type

enum

Default Value

auto

Supported Values

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`.
viewport-glyph: When `symbol-placement` is set to `point`, aligns text to the x-axis of the viewport. When `symbol-placement` is set to `line` or `line-center`, aligns glyphs to the x-axis of the viewport and places them along the line.
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

textField

Expression Parameters

zoom

### `textField` 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.

Type: formatted
Default Value
Expression Parameters: zoom, feature

### `textFont` Font stack to use for displaying text.

Type: array
Default Value: [Open Sans Regular,Arial Unicode MS Regular]
Requires: textField
Supported Style Functions: camera
Expression Parameters: zoom, feature

### `textSize` Font size.

Type: number
Default Value: 16
Units: pixels
Minimum: 0
Requires: textField
Expression Parameters: zoom, feature

### `textMaxWidth` The maximum line width for text wrapping.

Type: number
Default Value: 10
Units: ems
Minimum: 0
Requires: textField
Supported Style Functions: camera
Expression Parameters: zoom, feature

### `textLineHeight` Text leading value for multiLine text.

Type: number
Default Value: 1.2
Units: ems
Requires: textField
Expression Parameters: zoom

### `textLetterSpacing` Text tracking amount.

Type: number
Default Value: 0
Units: ems
Requires: textField
Supported Style Functions: camera
Expression Parameters: zoom, feature

### `textJustify` Text justification options.

Type

enum

Default Value

center

Supported Values

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

textField

Supported Style Functions

camera

Expression Parameters

zoom, feature

### `textAnchor` Part of the text placed closest to the anchor.

Type

enum

Default Value

center

Supported Values

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

textField

Disabled By

textVariableAnchor

Supported Style Functions

camera

Expression Parameters

zoom, feature

### `textMaxAngle` Maximum angle change between adjacent characters.

Type: number
Default Value: 45
Units: degrees
Requires: textField
Expression Parameters: zoom

### `textRotate` Rotates the text clockwise.

Type: number
Default Value: 0
Units: degrees
Requires: textField
Expression Parameters: zoom, feature

### `textPadding` Size of the additional area around the text bounding box used for detecting symbol collisions.

Type: number
Default Value: 2
Units: pixels
Minimum: 0
Requires: textField
Expression Parameters: zoom

### `textKeepUpright` If true, the text may be flipped vertically to prevent it from being rendered upsideDown.

Type: boolean
Default Value: true
Requires: textField
Expression Parameters: zoom

### `textTransform` Specifies how to capitalize text, similar to the CSS `textTransform` property.

Type

enum

Default Value

none

Supported Values

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

textField

Expression Parameters

zoom, feature

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

Type: array
Default Value: [0,0]
Units: ems
Requires: textField
Disabled By: textRadialOffset
Expression Parameters: zoom, feature

### `textAllowOverlap` If true, the text will be visible even if it collides with other previously drawn symbols.

Type: boolean
Default Value: false
Requires: textField
Disabled By: textOverlap
Expression Parameters: zoom

### `textIgnorePlacement` If true, other symbols can be visible even if they collide with the text.

Type: boolean
Default Value: false
Requires: textField
Expression Parameters: zoom

### `textOptional` If true, icons will display without their corresponding text when the text collides with other symbols and the icon does not.

Type: boolean
Default Value: false
Requires: textField, iconImage
Expression Parameters: zoom

### `visibility` Whether this layer is displayed.

Type

enum

Default Value

visible

Supported Values

visible: The layer is shown.
none: The layer is not shown.

### `iconOpacity` The opacity at which the icon will be drawn.

Type: number
Default Value: 1
Minimum: 0
Maximum: 1
Requires: iconImage
Expression Parameters: zoom, feature, feature-state

### `iconOpacityTransition` The transition affecting any changes to this layer’s iconOpacity property.

Type: { duration, delay }
Units: milliseconds
Default Value: {duration: 300, delay: 0}

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

Type: color
Default Value: #000000
Requires: iconImage
Expression Parameters: zoom, feature, feature-state

### `iconColorTransition` The transition affecting any changes to this layer’s iconColor property.

Type: { duration, delay }
Units: milliseconds
Default Value: {duration: 300, delay: 0}

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

Type: color
Default Value: rgba(0, 0, 0, 0)
Requires: iconImage
Expression Parameters: zoom, feature, feature-state

### `iconHaloColorTransition` The transition affecting any changes to this layer’s iconHaloColor property.

Type: { duration, delay }
Units: milliseconds
Default Value: {duration: 300, delay: 0}

### `iconHaloWidth` Distance of halo to the icon outline. The unit is in pixels only for SDF sprites that were created with a blur radius of 8, multiplied by the display density. I.e., the radius needs to be 16 for `@2x` sprites, etc.

Type: number
Default Value: 0
Units: pixels
Minimum: 0
Requires: iconImage
Expression Parameters: zoom, feature, feature-state

### `iconHaloWidthTransition` The transition affecting any changes to this layer’s iconHaloWidth property.

Type: { duration, delay }
Units: milliseconds
Default Value: {duration: 300, delay: 0}

### `iconHaloBlur` Fade out the halo towards the outside.

Type: number
Default Value: 0
Units: pixels
Minimum: 0
Requires: iconImage
Expression Parameters: zoom, feature, feature-state

### `iconHaloBlurTransition` The transition affecting any changes to this layer’s iconHaloBlur property.

Type: { duration, delay }
Units: milliseconds
Default Value: {duration: 300, delay: 0}

### `iconTranslate` 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.

Type: array
Default Value: [0,0]
Units: pixels
Requires: iconImage
Expression Parameters: zoom

### `iconTranslateTransition` The transition affecting any changes to this layer’s iconTranslate property.

Type: { duration, delay }
Units: milliseconds
Default Value: {duration: 300, delay: 0}

### `iconTranslateAnchor` Controls the frame of reference for `iconTranslate`.

Type

enum

Default Value

map

Supported Values

map: Icons are translated relative to the map.
viewport: Icons are translated relative to the viewport.

Requires

iconImage, iconTranslate

Expression Parameters

zoom

### `textOpacity` The opacity at which the text will be drawn.

Type: number
Default Value: 1
Minimum: 0
Maximum: 1
Requires: textField
Expression Parameters: zoom, feature, feature-state

### `textOpacityTransition` The transition affecting any changes to this layer’s textOpacity property.

Type: { duration, delay }
Units: milliseconds
Default Value: {duration: 300, delay: 0}

### `textColor` The color with which the text will be drawn.

Type: color
Default Value: #000000
Requires: textField
Expression Parameters: zoom, feature, feature-state

### `textColorTransition` The transition affecting any changes to this layer’s textColor property.

Type: { duration, delay }
Units: milliseconds
Default Value: {duration: 300, delay: 0}

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

Type: color
Default Value: rgba(0, 0, 0, 0)
Requires: textField
Expression Parameters: zoom, feature, feature-state

### `textHaloColorTransition` The transition affecting any changes to this layer’s textHaloColor property.

Type: { duration, delay }
Units: milliseconds
Default Value: {duration: 300, delay: 0}

### `textHaloWidth` Distance of halo to the font outline. Max text halo width is 1/4 of the fontSize.

Type: number
Default Value: 0
Units: pixels
Minimum: 0
Requires: textField
Expression Parameters: zoom, feature, feature-state

### `textHaloWidthTransition` The transition affecting any changes to this layer’s textHaloWidth property.

Type: { duration, delay }
Units: milliseconds
Default Value: {duration: 300, delay: 0}

### `textHaloBlur` The halo's fadeout distance towards the outside.

Type: number
Default Value: 0
Units: pixels
Minimum: 0
Requires: textField
Expression Parameters: zoom, feature, feature-state

### `textHaloBlurTransition` The transition affecting any changes to this layer’s textHaloBlur property.

Type: { duration, delay }
Units: milliseconds
Default Value: {duration: 300, delay: 0}

### `textTranslate` 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.

Type: array
Default Value: [0,0]
Units: pixels
Requires: textField
Expression Parameters: zoom

### `textTranslateTransition` The transition affecting any changes to this layer’s textTranslate property.

Type: { duration, delay }
Units: milliseconds
Default Value: {duration: 300, delay: 0}

### `textTranslateAnchor` Controls the frame of reference for `textTranslate`.

Type

enum

Default Value

map

Supported Values

map: The text is translated relative to the map.
viewport: The text is translated relative to the viewport.

Requires

textField, textTranslate

Expression Parameters

zoom