Layer Types

Complete field reference

This guide explains the fields and shows them in use. For every key — type, default, allowed values, and description, generated from the schemas so it always matches the validator — see the generated Layers reference.

Layer Types

Layers define how your data is visualized on the map. maplibre-yaml supports all MapLibre layer types.

Common Properties

All layers share these base properties:

Property	Type	Default	Description
id *	string	—	Unique identifier for the layer
type *	string	—	Layer type (circle, line, fill, etc.)
source *	Source | string	—	Data source configuration or reference
source-layer	string	—	Source layer (for vector tiles)
minzoom	number	0	Minimum zoom level
maxzoom	number	24	Maximum zoom level
filter	Expression	—	Filter expression
visible	boolean	true	Initial visibility
label	string	—	Display label — chrome metadata. A labeled layer also gets a visibility checkbox on the params panel
toggleable	boolean	true	Allow users to toggle visibility; set false to keep a labeled layer off the params panel
before	string	—	Insert before this layer ID
interactive	object	—	Click/hover configuration
legend	object	—	Legend entry configuration
effect	object	—	Experimental: a registered shader effect (`type` + flat params) enhancing this layer; the layer itself is the effect's static fallback. In format v2 it lives under the layer's `runtime:`. See the Effects guide.

effect: (experimental)

Experimental

effect: and @maplibre-yaml/effects are experimental in 0.7: the key’s params and the effects API may change in a minor release.

An effect: block names a registered effect and carries its params flat beside type. The layer it sits on stays a complete, ordinary layer — it is what renders without the effects package, under an unsupported projection, and in the exported style.

Key	Type	Description
type	string	A registered effect: tonal-hatch or blueprint built in, or one page JavaScript registered.
any other key	per effect	The effect’s params, validated against its schema when @maplibre-yaml/effects is loaded.

Built-in params:

Effect	Layer type	Params (defaults)
tonal-hatch	fill-extrusion	ink (#4d4d4e), paper (#f9f3e3), atlas (hatch-atlas — an images: name), gain (0.72), outline (0.85), exaggerate (false)
blueprint	fill-extrusion	line (#cfeeff), ground (#1a56b0), grid (4 metres), gain (0.72)

type: map
id: blueprint-example
config:
  center: [-74.0118, 40.7075]
  zoom: 15.9
  pitch: 60
  mapStyle: "https://demotiles.maplibre.org/style.json"
sources:
  omt:
    type: vector
    url: "https://tiles.openfreemap.org/planet"
layers:
  - id: buildings
    type: fill-extrusion
    source: omt
    source-layer: building
    paint:
      fill-extrusion-color: "#1a56b0"
      fill-extrusion-height: ["coalesce", ["get", "render_height"], 10]
    effect:
      type: blueprint
      grid: 4

Without the package, validation reports one unimplemented warning per effect (never an error) and the layer renders statically. With it, a bad param is a positioned parse error. On mlym emit, each effect is one lossy warning: --strict refuses, --with-fallbacks ships the static layer (export classes). Full guide: Effects.

---

Circle Layer

Renders points as circles. Great for point data visualization.

Circle layer with data-driven radius

Circle Paint Properties

Property	Type	Default	Description
circle-radius	number | Expression	5	Circle radius in pixels
circle-color	color | Expression	"#000000"	Fill color
circle-opacity	number | Expression	1	Fill opacity (0-1)
circle-stroke-width	number | Expression	0	Stroke width in pixels
circle-stroke-color	color | Expression	"#000000"	Stroke color
circle-stroke-opacity	number | Expression	1	Stroke opacity (0-1)
circle-blur	number | Expression	0	Blur amount

Example

Basic

- id: points
  type: circle
  source:
    type: geojson
    url: "https://example.com/points.geojson"
  paint:
    circle-radius: 8
    circle-color: "#ff0000"

Data-Driven

- id: earthquakes
  type: circle
  source:
    type: geojson
    url: "https://example.com/earthquakes.geojson"
  paint:
    circle-radius:
      - interpolate
      - ["linear"]
      - ["get", "magnitude"]
      - 1
      - 4
      - 5
      - 12
      - 8
      - 24
    circle-color:
      - interpolate
      - ["linear"]
      - ["get", "magnitude"]
      - 1
      - "#ffffcc"
      - 5
      - "#fd8d3c"
      - 8
      - "#bd0026"

---

Line Layer

Renders lines and line strings. Perfect for routes, boundaries, and networks.

---

Color Relief Layer

Hypsometric tinting: each pixel of a raster-dem source is colored by its elevation. color-relief-color is a color ramp over the ["elevation"] expression, the way heatmap-color ramps over ["heatmap-density"]. Requires maplibre-gl 5.6 or later.

Paint property	Type	Description
color-relief-color	color expression	Ramp over ["elevation"] (interpolate or step)
color-relief-opacity	number	Layer opacity (0-1)

type: map
id: relief
config:
  center: [11.45, 47.2]
  zoom: 10
layers:
  - id: relief
    type: color-relief
    source:
      type: raster-dem
      url: https://demotiles.maplibre.org/terrain-tiles/tiles.json
      tileSize: 256
    paint:
      color-relief-color:
        - interpolate
        - ["linear"]
        - ["elevation"]
        - 400
        - "rgb(4, 0, 108)"
        - 1500
        - "rgb(39, 144, 116)"
        - 3500
        - "rgb(215, 5, 13)"

On a runtime below 5.6, <ml-map> skips color-relief layers with one console warning (a declared absence), and the rest of the document renders normally. On export the layer compiles through verbatim. mlym emit --target below 5.6 reports it as lossy. See the gallery example.