Mapstyle

KORTxyz-maplibre has two levels of map that can be specified through attributes. A mapstyle on top and basemapstyle below.

<kortxyz-maplibre
  mapstyle="./assets/skoledistrikter2024.json"
  basemapstyle="https://cdn.dataforsyningen.dk/assets/vector_tiles_assets/latest/styles/official/3857_skaermkort_moerkt.json?token=bfe350080dc1da9dbb948d6fd59a8e96"
>

Both is a reference to a Maplibre style which defines how maps are visually rendered in MapLibre GL–based applications. A style is a JSON document that describes data sources, layers, layout and paint properties, and global rendering settings. The specification is largely compatible with the Mapbox Style Specification (v8) and is the foundation for building interactive, vector‑based maps.

This page provides a practical overview of the structure, concepts, and common usage patterns of the MapLibre style spec.

What is a Style?

A style controls how geographic data is drawn, not the data itself. The same data source can be rendered in many different ways by changing the style.

A style JSON typically answers questions like:

• Which data sources should be used?
• Which layers should be rendered, and in what order?
• How should features look at different zoom levels?
• How should labels, colors, lines, and symbols behave?

Top‑Level Structure

A MapLibre style is a single JSON object with the following top‑level properties:

{
  "version": 8,
  "name": "Example Style",
  "sources": {},
  "layers": [],
  "glyphs": "",
  "sprite": "",
  "metadata": {}
}

Required

• version – Style specification version (currently 8)
• sources – Data sources used by the style
• layers – Rendering rules, applied in order

Optional but Common

• name – Human‑readable name
• glyphs – URL template for font glyphs
• sprite – URL for icons and patterns
• metadata – Arbitrary application‑specific data

Sources

Sources define where the data comes from. Layers reference sources by name.

Common Source Types

Vector

"my-vector-source": {
  "type": "vector",
  "url": "https://example.com/tiles.json"
}

GeoJSON

"my-geojson": {
  "type": "geojson",
  "data": "https://example.com/data.geojson"
}

Raster

"satellite": {
  "type": "raster",
  "tiles": ["https://example.com/{z}/{x}/{y}.png"],
  "tileSize": 256
}

Sources may also support options such as minzoom, maxzoom, promoteId, and clustering (for GeoJSON).

Layers

Layers describe how features from a source are drawn. They are rendered in order, from bottom to top.

Each layer includes:

• An id
• A type
• A source
• Optional filters, layout, and paint rules

{
  "id": "roads",
  "type": "line",
  "source": "my-vector-source",
  "source-layer": "transportation",
  "paint": {
    "line-color": "#ff0000",
    "line-width": 2
  }
}

Layer Types

The type determines which properties are available.

Layout vs Paint Properties

Each layer can define two types of properties:

Layout

• Affects feature placement
• Evaluated once per feature
• Examples: label placement, icon size, line joins

"layout": {
  "line-cap": "round"
}

Paint

• Affects visual appearance
• Can change continuously with zoom
• Examples: color, opacity, width

"paint": {
  "line-opacity": 0.8
}

Filters

Filters limit which features a layer applies to.

"filter": [
  "==",
  ["get", "class"],
  "primary"
]

Filters use an expression syntax and are commonly based on feature properties, geometry type, or zoom level.

Expressions

Expressions allow data‑driven styling. They are used throughout the style spec for filters, layout, and paint properties.

Example: line width based on zoom

"line-width": [
  "interpolate",
  ["linear"],
  ["zoom"],
  5, 1,
  12, 4
]

Expressions enable:

• Zoom‑dependent styling
• Property‑based styling
• Conditional logic

Sprites and Glyphs

Sprites

Sprites provide icons and patterns for symbol and fill layers.

"sprite": "https://example.com/sprites/sprite"

Glyphs

Glyphs define where fonts are loaded from for text rendering.

"glyphs": "https://example.com/fonts/{fontstack}/{range}.pbf"

Metadata

The metadata object can store arbitrary application‑specific information. MapLibre itself ignores this section.

"metadata": {
  "app": "kortxyz",
  "theme": "dark"
}

Summary

The MapLibre Style Specification:

• Separates data from visualization
• Enables powerful, data‑driven map rendering
• Uses a declarative JSON format
• Supports dynamic, interactive, and scalable maps

Understanding the style spec is essential for building custom cartography with MapLibre.

This page provides an overview. For full details, consult the official MapLibre Style Specification reference.