Map block (v1)
A type: map block — the unit <ml-map src> and mlym validate consume. This is the default format (version: 1, or no version: key). For narrative and examples see Map Configuration.
Type: "map" · Required
Block type
Type: string · Required
Unique block identifier
version
Section titled “version”Type: 1
Format version — v1 documents may state version: 1
className
Section titled “className”Type: string
CSS class name for container
Type: string
Inline CSS styles for container
config
Section titled “config”Type: object · Required
Map configuration with MapLibre options
center
Section titled “center”Path: config.center · Type: [number, number] · Required
Initial map center [longitude, latitude]
Path: config.zoom · Type: number · Required · Range: 0 to 24
Initial zoom level (0-24)
mapStyle
Section titled “mapStyle”Path: config.mapStyle · Type: string (URL) | any
MapLibre style URL or style object. Optional when global config.defaultMapStyle is set.
Path: config.pitch · Type: number · Default: 0 · Range: 0 to 85
Camera pitch angle in degrees (0-85)
bearing
Section titled “bearing”Path: config.bearing · Type: number · Default: 0 · Range: -180 to 180
Camera bearing (rotation) in degrees (-180 to 180)
bounds
Section titled “bounds”Path: config.bounds · Type: [number, number, number, number] | number[]
Fit map to bounds
Path: config.fitTo · Type: object
Fit the initial camera to a GeoJSON source’s data (wins over bounds)
source
Section titled “source”Path: config.fitTo.source · Type: string · Required · Min length: 1
Name of a GeoJSON entry in sources: whose data the camera frames
padding
Section titled “padding”Path: config.fitTo.padding · Type: number · Minimum: 0
Padding in pixels around the fitted bounds
maxZoom
Section titled “maxZoom”Path: config.fitTo.maxZoom · Type: number · Range: 0 to 24
Upper zoom limit for the fit (a single point would otherwise zoom all the way in)
minZoom
Section titled “minZoom”Path: config.minZoom · Type: number · Range: 0 to 24
Minimum zoom level
maxZoom
Section titled “maxZoom”Path: config.maxZoom · Type: number · Range: 0 to 24
Maximum zoom level
minPitch
Section titled “minPitch”Path: config.minPitch · Type: number · Range: 0 to 85
Minimum pitch
maxPitch
Section titled “maxPitch”Path: config.maxPitch · Type: number · Range: 0 to 85
Maximum pitch
maxBounds
Section titled “maxBounds”Path: config.maxBounds · Type: [number, number, number, number]
Maximum geographic bounds
interactive
Section titled “interactive”Path: config.interactive · Type: boolean · Default: true
Enable map interaction
scrollZoom
Section titled “scrollZoom”Path: config.scrollZoom · Type: boolean
Enable scroll to zoom
boxZoom
Section titled “boxZoom”Path: config.boxZoom · Type: boolean
Enable box zoom (shift+drag)
dragRotate
Section titled “dragRotate”Path: config.dragRotate · Type: boolean
Enable drag to rotate
dragPan
Section titled “dragPan”Path: config.dragPan · Type: boolean
Enable drag to pan
keyboard
Section titled “keyboard”Path: config.keyboard · Type: boolean
Enable keyboard shortcuts
doubleClickZoom
Section titled “doubleClickZoom”Path: config.doubleClickZoom · Type: boolean
Enable double-click zoom
touchZoomRotate
Section titled “touchZoomRotate”Path: config.touchZoomRotate · Type: boolean
Enable touch zoom/rotate
touchPitch
Section titled “touchPitch”Path: config.touchPitch · Type: boolean
Enable touch pitch
Path: config.hash · Type: boolean
Sync map state with URL hash
attributionControl
Section titled “attributionControl”Path: config.attributionControl · Type: boolean
Show attribution control
logoPosition
Section titled “logoPosition”Path: config.logoPosition · Type: "top-left" | "top-right" | "bottom-left" | "bottom-right"
MapLibre logo position
fadeDuration
Section titled “fadeDuration”Path: config.fadeDuration · Type: number
Fade duration in milliseconds
crossSourceCollisions
Section titled “crossSourceCollisions”Path: config.crossSourceCollisions · Type: boolean
Check for cross-source collisions
antialias
Section titled “antialias”Path: config.antialias · Type: boolean
Enable antialiasing
refreshExpiredTiles
Section titled “refreshExpiredTiles”Path: config.refreshExpiredTiles · Type: boolean
Refresh expired tiles
renderWorldCopies
Section titled “renderWorldCopies”Path: config.renderWorldCopies · Type: boolean
Render multiple world copies
locale
Section titled “locale”Path: config.locale · Type: map of string
Localization strings
maxTileCacheSize
Section titled “maxTileCacheSize”Path: config.maxTileCacheSize · Type: number
Maximum tiles to cache
localIdeographFontFamily
Section titled “localIdeographFontFamily”Path: config.localIdeographFontFamily · Type: string
Font for CJK characters
trackResize
Section titled “trackResize”Path: config.trackResize · Type: boolean
Track container resize
preserveDrawingBuffer
Section titled “preserveDrawingBuffer”Path: config.preserveDrawingBuffer · Type: boolean
Preserve drawing buffer
failIfMajorPerformanceCaveat
Section titled “failIfMajorPerformanceCaveat”Path: config.failIfMajorPerformanceCaveat · Type: boolean
Fail if major performance caveat
sources
Section titled “sources”Type: map of object
Map sources
<source-id>
Section titled “<source-id>”Path: sources.<source-id> · Type: object
See the Sources reference.
layers
Section titled “layers”Type: object[] · Default: []
Map layers
Each entry: see the Layers reference.
controls
Section titled “controls”Type: object
Map controls
navigation
Section titled “navigation”Path: controls.navigation · Type: boolean | object
Navigation controls (zoom, rotation)
enabled
Section titled “enabled”Path: controls.navigation.enabled · Type: boolean · Required
Whether control is enabled
position
Section titled “position”Path: controls.navigation.position · Type: "top-left" | "top-right" | "bottom-left" | "bottom-right"
Control position
geolocate
Section titled “geolocate”Path: controls.geolocate · Type: boolean | object
Geolocation control
Same shape as controls.navigation.
Path: controls.scale · Type: boolean | object
Scale control
Same shape as controls.navigation.
fullscreen
Section titled “fullscreen”Path: controls.fullscreen · Type: boolean | object
Fullscreen control
Same shape as controls.navigation.
attribution
Section titled “attribution”Path: controls.attribution · Type: boolean | object
Attribution control
enabled
Section titled “enabled”Path: controls.attribution.enabled · Type: boolean
Whether control is enabled
position
Section titled “position”Path: controls.attribution.position · Type: "top-left" | "top-right" | "bottom-left" | "bottom-right"
Control position
compact
Section titled “compact”Path: controls.attribution.compact · Type: boolean
Render the attribution control in its compact form
customAttribution
Section titled “customAttribution”Path: controls.attribution.customAttribution · Type: string | string[]
Additional attribution string(s) to display
Path: controls.globe · Type: boolean | object
Globe/mercator projection toggle (maplibre-gl >= 5.0.0)
Same shape as controls.navigation.
terrain
Section titled “terrain”Path: controls.terrain · Type: boolean | object
3D terrain on/off toggle — toggles the document’s terrain:
Same shape as controls.navigation.
legend
Section titled “legend”Type: object
Legend configuration
position
Section titled “position”Path: legend.position · Type: "top-left" | "top-right" | "bottom-left" | "bottom-right" · Default: "top-left"
Legend position
Path: legend.title · Type: string
Legend title
collapsed
Section titled “collapsed”Path: legend.collapsed · Type: boolean · Default: false
Start collapsed
Path: legend.items · Type: object[]
Custom legend items (overrides layer legends)
Path: legend.items[].color · Type: string · Required
Item color
Path: legend.items[].label · Type: string · Required
Item label
Path: legend.items[].shape · Type: "circle" | "square" | "line" | "icon" · Default: "square"
Symbol shape
Path: legend.items[].icon · Type: string
Icon name/URL (for shape: icon)
Type: map of object
Runtime-tunable values, readable from expressions via global-state
<state-key>
Section titled “<state-key>”Path: state.<state-key> · Type: object
default
Section titled “default”Path: state.<state-key>.default · Type: any
Initial value, read by global-state
parameters
Section titled “parameters”Type: map of object
Presentation metadata for state keys — label, type, range
<state-key>
Section titled “<state-key>”Path: parameters.<state-key> · Type: object
Path: parameters.<state-key>.label · Type: string
Human-readable control label
Path: parameters.<state-key>.type · Type: string
Params-panel control kind: enum/select (dropdown over values), range (slider over min/max/step), or toggle (checkbox). When omitted it is inferred: values gives a dropdown, a boolean default gives a toggle; other values render no control
values
Section titled “values”Path: parameters.<state-key>.values · Type: array
Allowed values, for enum parameters
Path: parameters.<state-key>.min · Type: number
Lower bound, for range parameters
Path: parameters.<state-key>.max · Type: number
Upper bound, for range parameters
Path: parameters.<state-key>.step · Type: number
Increment, for range parameters
markers
Section titled “markers”Type: object[]
Standalone markers — DOM pins live, symbol layers + sprite on export
Path: markers[].at · Type: [number, number] · Required
Marker position [lng, lat]
Path: markers[].color · Type: string
Pin color (the default pin only; ignored when icon is set)
Path: markers[].size · Type: number · Greater than: 0
Scale multiplier for the pin (1 = MapLibre’s default size)
Path: markers[].icon · Type: string
Image URL replacing the default pin
Path: markers[].popup · Type: (map of object[])[]
Popup opened by clicking the marker (same structured content as layer popups)
Same shape as layers[].interactive.hover.popup.
popups
Section titled “popups”Type: object[]
Standalone popups open at a coordinate — no layer, no marker
Path: popups[].at · Type: [number, number] · Required
Popup anchor position [lng, lat]
content
Section titled “content”Path: popups[].content · Type: (map of object[])[] · Required
Popup content (same structured items as layer popups; str: for text)
Each entry has the same shape as layers[].interactive.hover.popup[].
closeButton
Section titled “closeButton”Path: popups[].closeButton · Type: boolean
Show the close button (MapLibre default: true)
closeOnClick
Section titled “closeOnClick”Path: popups[].closeOnClick · Type: boolean
Close when the map is clicked (MapLibre default: true)
maxWidth
Section titled “maxWidth”Path: popups[].maxWidth · Type: string
CSS max-width of the popup, e.g. “300px” (MapLibre default: 240px)
images
Section titled “images”Type: map of string | object
Named images for symbol layers and patterns — loaded live, merged into the sprite on export
<image-id>
Section titled “<image-id>”Path: images.<image-id> · Type: string | object
Path: images.<image-id>.url · Type: string · Required
Image URL
Path: images.<image-id>.sdf · Type: boolean
Treat as a signed-distance-field icon (tintable via icon-color)
pixelRatio
Section titled “pixelRatio”Path: images.<image-id>.pixelRatio · Type: number · Greater than: 0
Source density — 2 means the file is @2x (half its pixels in CSS px)
terrain
Section titled “terrain”Type: object
3D terrain from a raster-dem source — setTerrain live, style.json terrain on export
source
Section titled “source”Path: terrain.source · Type: string · Required · Min length: 1
Name of the raster-dem source supplying elevation
exaggeration
Section titled “exaggeration”Path: terrain.exaggeration · Type: number · Minimum: 0
Vertical exaggeration multiplier (spec default 1)
Type: object
Sky, fog, and globe atmosphere — setSky live (maplibre-gl >= 4.5), style.json sky on export
sky-color
Section titled “sky-color”Path: sky.sky-color · Type: string | array
Color of the sky above the horizon
horizon-color
Section titled “horizon-color”Path: sky.horizon-color · Type: string | array
Color at the horizon, where sky meets fog
fog-color
Section titled “fog-color”Path: sky.fog-color · Type: string | array
Color of the fog over distant 3D terrain
sky-horizon-blend
Section titled “sky-horizon-blend”Path: sky.sky-horizon-blend · Type: number | array
How far the horizon color blends up into the sky (0-1)
horizon-fog-blend
Section titled “horizon-fog-blend”Path: sky.horizon-fog-blend · Type: number | array
How far the horizon color blends down into the fog (0-1)
fog-ground-blend
Section titled “fog-ground-blend”Path: sky.fog-ground-blend · Type: number | array
Where fog starts over terrain: 0 at the camera, 1 at the horizon
atmosphere-blend
Section titled “atmosphere-blend”Path: sky.atmosphere-blend · Type: number | array
Globe atmosphere opacity (0-1); draws under globe projection only (maplibre-gl >= 5)
projection
Section titled “projection”Type: object
Map projection (globe needs maplibre-gl >= 5) — style.json projection on export
Path: projection.type · Type: "mercator" | "globe" · Required
Projection: mercator (default) or globe (maplibre-gl >= 5.0.0)
Type: object
The style-spec light shading fill-extrusion faces — map.setLight live, style.json light on export
anchor
Section titled “anchor”Path: light.anchor · Type: "map" | "viewport" | array
map fixes the light to the map (it turns with the bearing); viewport (default) fixes it to the screen
Allowed values: map, viewport
position
Section titled “position”Path: light.position · Type: [number, number, number] | array
[radial, azimuthal°, polar°] — distance from the centre of the base of an object, direction clockwise from north (0° = north at anchor map), height above the horizon (0° = overhead). Default [1.15, 210, 30]
Path: light.color · Type: string | array
Light color (default white)
intensity
Section titled “intensity”Path: light.intensity · Type: number | array
Light intensity, 0–1; higher is more extreme contrast (default 0.5)