Layers
An entry of a block’s layers: list: either a full layer (the type key selects the variant) or a $ref to a named layer in a root document. For narrative and examples see Layer Types and Interactivity.
Definition (by type)
Section titled “Definition (by type)”One of 10 variants, selected by type: circle, line, fill, symbol, raster, fill-extrusion, heatmap, hillshade, color-relief, background.
Common fields
Section titled “Common fields”Accepted by every variant that lists them below.
Path: layers[].id · Type: string · Required
Unique layer identifier
Path: layers[].label · Type: string
Human-readable layer label
source
Section titled “source”Path: layers[].source · Type: object | string · Required
Layer source: inline definition, { $ref: ’#/sources/name’ } reference, or named-source string
Inline source
Section titled “Inline source”See the Sources reference.
Reference ($ref)
Section titled “Reference ($ref)”Source reference
Path: layers[].source.$ref · Type: string · Required
Reference to a root-level source (e.g., ”#/sources/name”)
source-layer
Section titled “source-layer”Path: layers[].source-layer · Type: string
Source layer name (for vector sources)
minzoom
Section titled “minzoom”Path: layers[].minzoom · Type: number · Range: 0 to 24
Minimum zoom level to show layer
maxzoom
Section titled “maxzoom”Path: layers[].maxzoom · Type: number · Range: 0 to 24
Maximum zoom level to show layer
filter
Section titled “filter”Path: layers[].filter · Type: array
MapLibre filter expression
visible
Section titled “visible”Path: layers[].visible · Type: boolean · Default: true
Initial visibility state
toggleable
Section titled “toggleable”Path: layers[].toggleable · Type: boolean · Default: true
Allow users to toggle visibility
before
Section titled “before”Path: layers[].before · Type: string
Layer ID to insert this layer before
interactive
Section titled “interactive”Path: layers[].interactive · Type: object
Interactive event configuration
Path: layers[].interactive.hover · Type: object
Hover behavior
cursor
Section titled “cursor”Path: layers[].interactive.hover.cursor · Type: string
CSS cursor style (e.g., “pointer”)
highlight
Section titled “highlight”Path: layers[].interactive.hover.highlight · Type: boolean
Highlight feature on hover
Path: layers[].interactive.hover.emit · Type: object
Dispatch a named host event with a declarative payload once per feature entered on hover (per-feature dedupe, not per mousemove)
Path: layers[].interactive.hover.emit.event · Type: string · Required
Named event dispatched to the host handler map
payload
Section titled “payload”Path: layers[].interactive.hover.emit.payload · Type: map of object
Declarative payload: named keys projected from feature properties
Path: layers[].interactive.hover.emit.payload.<key> · Type: object
Declarative payload projection item
property
Section titled “property”Path: layers[].interactive.hover.emit.payload.<key>.property · Type: string
Feature property name to project
Path: layers[].interactive.hover.emit.payload.<key>.else · Type: string
Fallback value when the property is missing
Path: layers[].interactive.hover.emit.payload.<key>.str · Type: string
Static literal value
Path: layers[].interactive.hover.popup · Type: (map of object[])[]
Popup shown while hovering a feature (no close button; dismissed on leave). A pinned click popup suppresses hover popups until it is dismissed. Touch has no hover: tap uses click.popup.
Path: layers[].interactive.hover.popup[].<tag> · Type: object[]
Path: layers[].interactive.hover.popup[].<tag>[].str · Type: string | object
Static text; an !html-tagged value carries raw markup
Path: layers[].interactive.hover.popup[].<tag>[].str.$html · Type: string · Required
property
Section titled “property”Path: layers[].interactive.hover.popup[].<tag>[].property · Type: string
Feature property name
Path: layers[].interactive.hover.popup[].<tag>[].else · Type: string
Fallback value if property missing
format
Section titled “format”Path: layers[].interactive.hover.popup[].<tag>[].format · Type: string
Number format string (e.g., “,.0f”)
Path: layers[].interactive.hover.popup[].<tag>[].href · Type: string (URL)
Link URL
Path: layers[].interactive.hover.popup[].<tag>[].text · Type: string
Link text
Path: layers[].interactive.hover.popup[].<tag>[].src · Type: string (URL)
Image/iframe source
Path: layers[].interactive.hover.popup[].<tag>[].alt · Type: string
Image alt text
Path: layers[].interactive.click · Type: object
Click behavior
Path: layers[].interactive.click.popup · Type: (map of object[])[]
Popup content to display
Same shape as layers[].interactive.hover.popup.
action
Section titled “action”Path: layers[].interactive.click.action · Type: string · Deprecated
Custom action name to trigger
Path: layers[].interactive.click.flyTo · Type: object
Fly to location on click
center
Section titled “center”Path: layers[].interactive.click.flyTo.center · Type: [number, number]
Target center [longitude, latitude]; defaults to the clicked point
Path: layers[].interactive.click.flyTo.zoom · Type: number · Range: 0 to 24
Target zoom level; MapLibre keeps the current zoom when unset
duration
Section titled “duration”Path: layers[].interactive.click.flyTo.duration · Type: number
Animation duration in milliseconds; MapLibre’s default when unset
zoomToFeature
Section titled “zoomToFeature”Path: layers[].interactive.click.zoomToFeature · Type: object
Fit the camera to the clicked feature’s own bounds on click
padding
Section titled “padding”Path: layers[].interactive.click.zoomToFeature.padding · Type: number
Padding in pixels around the fitted bounds
maxZoom
Section titled “maxZoom”Path: layers[].interactive.click.zoomToFeature.maxZoom · Type: number · Range: 0 to 24
Maximum zoom level when fitting the feature’s bounds
duration
Section titled “duration”Path: layers[].interactive.click.zoomToFeature.duration · Type: number
Animation duration in milliseconds
Path: layers[].interactive.click.emit · Type: object
Dispatch a named host event with a declarative payload on click
Same shape as layers[].interactive.hover.emit.
mouseenter
Section titled “mouseenter”Path: layers[].interactive.mouseenter · Type: object
Legacy mouse-enter trigger. Its only key, action, is deprecated and never dispatched; use hover or listen for ml-map:layer-hover
action
Section titled “action”Path: layers[].interactive.mouseenter.action · Type: string · Deprecated
Custom action on mouse enter
mouseleave
Section titled “mouseleave”Path: layers[].interactive.mouseleave · Type: object
Legacy mouse-leave trigger. Its only key, action, is deprecated and never dispatched; use hover or listen for ml-map:layer-hover
action
Section titled “action”Path: layers[].interactive.mouseleave.action · Type: string · Deprecated
Custom action on mouse leave
legend
Section titled “legend”Path: layers[].legend · Type: object
Legend configuration
Path: layers[].legend.color · Type: string · Required
CSS color value
Path: layers[].legend.label · Type: string · Required
Legend label text
Path: layers[].legend.shape · Type: "circle" | "square" | "line" | "icon" · Default: "square"
Symbol shape
Path: layers[].legend.icon · Type: string
Icon name or URL (for shape: icon)
effect
Section titled “effect”Path: layers[].effect · Type: object
Experimental: a registered shader effect (type + flat params) that enhances this layer; the layer itself is the static fallback
Path: layers[].effect.type · Type: string · Required · Min length: 1
A registered effect type, e.g. tonal-hatch or blueprint
metadata
Section titled “metadata”Path: layers[].metadata · Type: map of any
Custom metadata
type: circle
Section titled “type: circle”Common fields: id, label, source, source-layer, minzoom, maxzoom, filter, visible, toggleable, before, interactive, legend, effect, metadata.
Path: layers[].type · Type: "circle" · Required
Layer type
Path: layers[].paint · Type: object
Circle paint properties
| Property | Type | Notes |
|---|---|---|
circle-radius | number | array | Number value or MapLibre expression |
circle-color | string | array | Color value or MapLibre expression |
circle-blur | number | array | Number value or MapLibre expression |
circle-opacity | number | array | Number value or MapLibre expression |
circle-stroke-width | number | array | Number value or MapLibre expression |
circle-stroke-color | string | array | Color value or MapLibre expression |
circle-stroke-opacity | number | array | Number value or MapLibre expression |
circle-pitch-scale | "map" | "viewport" | One of map, viewport. |
circle-pitch-alignment | "map" | "viewport" | One of map, viewport. |
circle-translate | [number, number] | |
circle-translate-anchor | "map" | "viewport" | One of map, viewport. |
Any other MapLibre paint property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
layout
Section titled “layout”Path: layers[].layout · Type: object
Circle layout properties
Any other MapLibre layout property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
type: line
Section titled “type: line”Common fields: id, label, source, source-layer, minzoom, maxzoom, filter, visible, toggleable, before, interactive, legend, effect, metadata.
Path: layers[].type · Type: "line" · Required
Layer type
Path: layers[].paint · Type: object
Line paint properties
| Property | Type | Notes |
|---|---|---|
line-opacity | number | array | Number value or MapLibre expression |
line-color | string | array | Color value or MapLibre expression |
line-width | number | array | Number value or MapLibre expression |
line-gap-width | number | array | Number value or MapLibre expression |
line-offset | number | array | Number value or MapLibre expression |
line-blur | number | array | Number value or MapLibre expression |
line-dasharray | number[] | |
line-pattern | string | array | |
line-gradient | string | array | Color value or MapLibre expression |
line-translate | [number, number] | |
line-translate-anchor | "map" | "viewport" | One of map, viewport. |
Any other MapLibre paint property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
layout
Section titled “layout”Path: layers[].layout · Type: object
Line layout properties
| Property | Type | Notes |
|---|---|---|
line-cap | "butt" | "round" | "square" | One of butt, round, square. |
line-join | "bevel" | "round" | "miter" | One of bevel, round, miter. |
line-miter-limit | number | |
line-round-limit | number | |
line-sort-key | number | array | Number value or MapLibre expression |
Any other MapLibre layout property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
type: fill
Section titled “type: fill”Common fields: id, label, source, source-layer, minzoom, maxzoom, filter, visible, toggleable, before, interactive, legend, effect, metadata.
Path: layers[].type · Type: "fill" · Required
Layer type
Path: layers[].paint · Type: object
Fill paint properties
| Property | Type | Notes |
|---|---|---|
fill-antialias | boolean | |
fill-opacity | number | array | Number value or MapLibre expression |
fill-color | string | array | Color value or MapLibre expression |
fill-outline-color | string | array | Color value or MapLibre expression |
fill-translate | [number, number] | |
fill-translate-anchor | "map" | "viewport" | One of map, viewport. |
fill-pattern | string | array |
Any other MapLibre paint property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
layout
Section titled “layout”Path: layers[].layout · Type: object
Fill layout properties
| Property | Type | Notes |
|---|---|---|
fill-sort-key | number | array | Number value or MapLibre expression |
Any other MapLibre layout property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
type: symbol
Section titled “type: symbol”Common fields: id, label, source, source-layer, minzoom, maxzoom, filter, visible, toggleable, before, interactive, legend, effect, metadata.
Path: layers[].type · Type: "symbol" · Required
Layer type
layout
Section titled “layout”Path: layers[].layout · Type: object
Symbol layout properties
| Property | Type | Notes |
|---|---|---|
symbol-placement | "point" | "line" | "line-center" | One of point, line, line-center. |
symbol-spacing | number | |
symbol-avoid-edges | boolean | |
symbol-sort-key | number | array | Number value or MapLibre expression |
symbol-z-order | "auto" | "viewport-y" | "source" | One of auto, viewport-y, source. |
icon-allow-overlap | boolean | |
icon-ignore-placement | boolean | |
icon-optional | boolean | |
icon-rotation-alignment | "map" | "viewport" | "auto" | One of map, viewport, auto. |
icon-size | number | array | Number value or MapLibre expression |
icon-text-fit | "none" | "width" | "height" | "both" | One of none, width, height, both. |
icon-text-fit-padding | [number, number, number, number] | |
icon-image | string | array | |
icon-rotate | number | array | Number value or MapLibre expression |
icon-padding | number | |
icon-keep-upright | boolean | |
icon-offset | [number, number] | |
icon-anchor | string | One of center, left, right, top, bottom, top-left, top-right, bottom-left, bottom-right. |
icon-pitch-alignment | "map" | "viewport" | "auto" | One of map, viewport, auto. |
text-pitch-alignment | "map" | "viewport" | "auto" | One of map, viewport, auto. |
text-rotation-alignment | "map" | "viewport" | "auto" | One of map, viewport, auto. |
text-field | string | array | |
text-font | string[] | |
text-size | number | array | Number value or MapLibre expression |
text-max-width | number | array | Number value or MapLibre expression |
text-line-height | number | |
text-letter-spacing | number | |
text-justify | "auto" | "left" | "center" | "right" | One of auto, left, center, right. |
text-radial-offset | number | |
text-variable-anchor | string[] | |
text-anchor | string | One of center, left, right, top, bottom, top-left, top-right, bottom-left, bottom-right. |
text-max-angle | number | |
text-rotate | number | array | Number value or MapLibre expression |
text-padding | number | |
text-keep-upright | boolean | |
text-transform | "none" | "uppercase" | "lowercase" | One of none, uppercase, lowercase. |
text-offset | [number, number] | |
text-allow-overlap | boolean | |
text-ignore-placement | boolean | |
text-optional | boolean |
Any other MapLibre layout property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
Path: layers[].paint · Type: object
Symbol paint properties
| Property | Type | Notes |
|---|---|---|
icon-opacity | number | array | Number value or MapLibre expression |
icon-color | string | array | Color value or MapLibre expression |
icon-halo-color | string | array | Color value or MapLibre expression |
icon-halo-width | number | array | Number value or MapLibre expression |
icon-halo-blur | number | array | Number value or MapLibre expression |
icon-translate | [number, number] | |
icon-translate-anchor | "map" | "viewport" | One of map, viewport. |
text-opacity | number | array | Number value or MapLibre expression |
text-color | string | array | Color value or MapLibre expression |
text-halo-color | string | array | Color value or MapLibre expression |
text-halo-width | number | array | Number value or MapLibre expression |
text-halo-blur | number | array | Number value or MapLibre expression |
text-translate | [number, number] | |
text-translate-anchor | "map" | "viewport" | One of map, viewport. |
Any other MapLibre paint property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
type: raster
Section titled “type: raster”Common fields: id, label, source, source-layer, minzoom, maxzoom, filter, visible, toggleable, before, interactive, legend, effect, metadata.
Path: layers[].type · Type: "raster" · Required
Layer type
Path: layers[].paint · Type: object
Raster paint properties
| Property | Type | Notes |
|---|---|---|
raster-opacity | number | array | Number value or MapLibre expression |
raster-hue-rotate | number | array | Number value or MapLibre expression |
raster-brightness-min | number | array | Number value or MapLibre expression |
raster-brightness-max | number | array | Number value or MapLibre expression |
raster-saturation | number | array | Number value or MapLibre expression |
raster-contrast | number | array | Number value or MapLibre expression |
raster-resampling | "linear" | "nearest" | One of linear, nearest. |
raster-fade-duration | number |
Any other MapLibre paint property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
layout
Section titled “layout”Path: layers[].layout · Type: object
Raster layout properties
Any other MapLibre layout property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
type: fill-extrusion
Section titled “type: fill-extrusion”Common fields: id, label, source, source-layer, minzoom, maxzoom, filter, visible, toggleable, before, interactive, legend, effect, metadata.
Path: layers[].type · Type: "fill-extrusion" · Required
Layer type
Path: layers[].paint · Type: object
Fill extrusion paint properties
| Property | Type | Notes |
|---|---|---|
fill-extrusion-opacity | number | array | Number value or MapLibre expression |
fill-extrusion-color | string | array | Color value or MapLibre expression |
fill-extrusion-translate | [number, number] | |
fill-extrusion-translate-anchor | "map" | "viewport" | One of map, viewport. |
fill-extrusion-pattern | string | array | |
fill-extrusion-height | number | array | Number value or MapLibre expression |
fill-extrusion-base | number | array | Number value or MapLibre expression |
fill-extrusion-vertical-gradient | boolean |
Any other MapLibre paint property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
layout
Section titled “layout”Path: layers[].layout · Type: object
Fill extrusion layout properties
Any other MapLibre layout property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
type: heatmap
Section titled “type: heatmap”Common fields: id, label, source, source-layer, minzoom, maxzoom, filter, visible, toggleable, before, interactive, legend, effect, metadata.
Path: layers[].type · Type: "heatmap" · Required
Layer type
Path: layers[].paint · Type: object
Heatmap paint properties
| Property | Type | Notes |
|---|---|---|
heatmap-radius | number | array | Number value or MapLibre expression |
heatmap-weight | number | array | Number value or MapLibre expression |
heatmap-intensity | number | array | Number value or MapLibre expression |
heatmap-color | string | array | Color value or MapLibre expression |
heatmap-opacity | number | array | Number value or MapLibre expression |
Any other MapLibre paint property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
layout
Section titled “layout”Path: layers[].layout · Type: object
Heatmap layout properties
Any other MapLibre layout property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
type: hillshade
Section titled “type: hillshade”Common fields: id, label, source, source-layer, minzoom, maxzoom, filter, visible, toggleable, before, interactive, legend, effect, metadata.
Path: layers[].type · Type: "hillshade" · Required
Layer type
Path: layers[].paint · Type: object
Hillshade paint properties
| Property | Type | Notes |
|---|---|---|
hillshade-illumination-direction | number | number[] | array | A number, one number per light (multidirectional), or an expression |
hillshade-illumination-altitude | number | number[] | array | A number, one number per light (multidirectional), or an expression |
hillshade-illumination-anchor | "map" | "viewport" | One of map, viewport. |
hillshade-method | "standard" | "basic" | "combined" | "igor" | "multidirectional" | One of standard, basic, combined, igor, multidirectional. |
hillshade-exaggeration | number | array | Number value or MapLibre expression |
hillshade-shadow-color | string | string[] | array | A color, one color per light (multidirectional), or an expression |
hillshade-highlight-color | string | string[] | array | A color, one color per light (multidirectional), or an expression |
hillshade-accent-color | string | array | Color value or MapLibre expression |
Any other MapLibre paint property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
layout
Section titled “layout”Path: layers[].layout · Type: object
Hillshade layout properties
Any other MapLibre layout property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
type: color-relief
Section titled “type: color-relief”Common fields: id, label, source, source-layer, minzoom, maxzoom, filter, visible, toggleable, before, interactive, legend, effect, metadata.
Path: layers[].type · Type: "color-relief" · Required
Layer type (maplibre-gl >= 5.6)
Path: layers[].paint · Type: object
Color-relief paint properties
| Property | Type | Notes |
|---|---|---|
color-relief-color | string | array | Color ramp over [“elevation”] — an interpolate/step expression |
color-relief-opacity | number | array | Layer opacity (0-1) |
Any other MapLibre paint property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
layout
Section titled “layout”Path: layers[].layout · Type: object
Color-relief layout properties
Any other MapLibre layout property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
type: background
Section titled “type: background”Path: layers[].id · Type: string · Required
Unique layer identifier
Path: layers[].type · Type: "background" · Required
Layer type
Path: layers[].paint · Type: object
Background paint properties
| Property | Type | Notes |
|---|---|---|
background-color | string | array | Color value or MapLibre expression |
background-pattern | string | array | |
background-opacity | number | array | Number value or MapLibre expression |
Any other MapLibre paint property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
layout
Section titled “layout”Path: layers[].layout · Type: object
Background layout properties
Any other MapLibre layout property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.
metadata
Section titled “metadata”Path: layers[].metadata · Type: map of any
Custom metadata
Reference ($ref)
Section titled “Reference ($ref)”Layer reference
Path: layers[].$ref · Type: string · Required
Reference to global layer (e.g., ”#/layers/bikeLayer”)