Vector tile style support

A VectorTileLayer style defines how vector tile features are drawn. This page lists the supported style-layer types, layout and paint properties, and expression operators.

A style is a JSON document that identifies the data sources to draw and the style layers that control drawing order and appearance. Layout and paint properties define how each style layer is displayed.

A style specification defines the structure of this document, property names and value types, and expression syntax. The MapLibre style specification provides background on these concepts; the tables on this page describe the properties and operators supported by VectorTileLayer.

These properties belong to individual layers within the style JSON, rather than to the VectorTileLayer class. An expression must return a value of the type expected by the property, such as a number for circle-radius or a color for circle-color.

The legacy filter operators has-id and none are also supported.

Supported style layer types

The supported style layer types are background, fill, line, symbol, and circle. A style layer’s type determines which layout and paint properties it accepts.

Layout properties

Layout properties control placement and arrangement, such as line joins, icon placement, and text size. Set them in a style layer’s layout object, or update them with VectorTileLayer.setLayoutProperties().

This method replaces the style layer’s entire layout object. To preserve other layout properties, retrieve the current object with VectorTileLayer.getLayoutProperties() before updating it.

The visibility property is supported for all five style layer types. Background, fill, and circle style layers have no additional layout properties.

For a loaded VectorTileLayer named layer with a line style layer named roads, retrieve its layout properties and update the line joins while preserving the other properties:

const layoutProperties = layer.getLayoutProperties("roads");
layoutProperties["line-join"] = "round";
layer.setLayoutProperties("roads", layoutProperties);

Paint properties

Paint properties control appearance, such as colors, opacity, and line widths. Set them in a style layer’s paint object, or update them with VectorTileLayer.setPaintProperties().

This method replaces the style layer’s entire paint object. To preserve other paint properties, retrieve the current object with VectorTileLayer.getPaintProperties() before updating it.

For a loaded VectorTileLayer named layer with a line style layer named roads, retrieve its paint properties and update the line color and width while preserving the other properties:

const paintProperties = layer.getPaintProperties("roads");
paintProperties["line-color"] = "#237a57";
paintProperties["line-width"] = 3;
layer.setPaintProperties("roads", paintProperties);

Expressions

Expressions calculate style property values from feature attributes, zoom, and other values. Expression arrays begin with an operator name followed by its arguments.

The interpolate, interpolate-hcl, and interpolate-lab operators accept linear, exponential, and cubic-bezier interpolation modes. These modes are arguments to the interpolation operators, not standalone expression operators.

Partially supported formatting

VectorTileLayer recognizes format expressions, but does not support applying different fonts, colors, or text sizes to individual parts of a label. The text-font, text-color, and font-scale options within a format expression are ignored.

Examples

Given a circle style layer named earthquakes with a numeric mag feature attribute, the following example sets the circle color based on magnitude:

const paintProperties = layer.getPaintProperties("earthquakes");
paintProperties["circle-color"] = ["case", [">=", ["get", "mag"], 5], "#b33939", "#237a57"];
layer.setPaintProperties("earthquakes", paintProperties);

To vary circle size with zoom, use ["zoom"] as the input to an interpolate expression. This example increases the radius linearly from 2 pixels at zoom level 3 to 8 pixels at zoom level 10. The radius stays at 2 pixels below zoom level 3 and at 8 pixels above zoom level 10.

const paintProperties = layer.getPaintProperties("earthquakes");
paintProperties["circle-radius"] = ["interpolate", ["linear"], ["zoom"], 3, 2, 10, 8];
layer.setPaintProperties("earthquakes", paintProperties);

Limitations

The following styling limitations apply:

• Style layer types other than background, fill, line, symbol, and circle are not supported.
• Properties such as line-gradient, text-variable-anchor, icon-text-fit, and fill-sort-key are not supported.
• The symbol-avoid-edges layout property is recognized, but does not affect symbol placement.
• The following expression operators are explicitly unsupported: accumulated, collator, feature-state, heatmap-density, image, is-supported-script, line-progress, number-format, resolved-locale, and within.
• Expression output values must be compatible with the target property’s value type. For example, a color property requires a color value, while a size property requires a number.
• Using format to apply different fonts, colors, or text sizes to individual parts of a label is not supported. See Partially supported formatting.

Related resources

• VectorTileLayer API reference
• MapLibre style specification (external reference)
• VectorTileLayer from JSON sample