Skip to content
maplibre-yaml

Your First Map

This guide walks you through the fundamentals of maplibre-yaml configuration. By the end, you’ll understand how to create maps, configure their appearance, and add basic layers.

Map structure

Section titled “Map structure”

Every maplibre-yaml configuration has this basic structure:

type: map # Required: identifies this as a map block
id: my-map # Required: unique identifier


config: # Map settings
  center: [lng, lat]
  zoom: number
  mapStyle: "url"


layers: [] # Array of layer configurations


controls: {} # Optional: map controls

The config section

Section titled “The config section”

The config section defines the initial map view:

config:
  center: [-74.006, 40.7128] # New York City
  zoom: 12 # Street level
  mapStyle: "https://demotiles.maplibre.org/style.json"


  # Optional settings
  pitch: 45 # Tilt angle (0-85)
  bearing: -17 # Rotation (-180 to 180)
  minZoom: 2 # Minimum zoom level
  maxZoom: 18 # Maximum zoom level
Map with pitch and bearing applied

Coordinates

Section titled “Coordinates”

Coordinates in maplibre-yaml use [longitude, latitude] order (GeoJSON standard), not latitude/longitude:

# ✓ Correct: [longitude, latitude]
center: [-74.006, 40.7128]


# ✗ Wrong: [latitude, longitude]
center: [40.7128, -74.006]

Map styles

Section titled “Map styles”

The mapStyle property accepts any MapLibre-compatible style URL:

# MapLibre demo tiles (free, good for testing)
mapStyle: "https://demotiles.maplibre.org/style.json"


# Self-hosted style
mapStyle: "https://your-server.com/styles/dark.json"


# MapTiler (requires API key)
mapStyle: "https://api.maptiler.com/maps/streets/style.json?key=YOUR_KEY"

Adding a simple layer

Section titled “Adding a simple layer”

Layers display data on your map. Here’s a minimal circle layer:

layers:
  - id: my-points # Unique layer ID
    type: circle # Layer type
    source: # Data source
      type: geojson
      data: # Inline GeoJSON
        type: FeatureCollection
        features:
          - type: Feature
            geometry:
              type: Point
              coordinates: [-74.006, 40.7128]
            properties:
              name: "New York"
    paint: # Visual styling
      circle-radius: 10
      circle-color: "#3b82f6"
Three cities as circle markers

Map controls

Section titled “Map controls”

Add navigation and other controls:

controls:
  navigation: true # Zoom +/- buttons
  scale: true # Scale bar
  fullscreen: true # Fullscreen toggle
  geolocate: true # User location button
Map with navigation and scale controls

Putting it together

Section titled “Putting it together”

Here’s a complete example combining everything:

type: map
id: complete-example
config:
  center: [-98, 39]
  zoom: 4
  mapStyle: "https://demotiles.maplibre.org/style.json"
  minZoom: 2
  maxZoom: 18


layers:
  - id: cities
    type: circle
    source:
      type: geojson
      data:
        type: FeatureCollection
        features:
          - type: Feature
            geometry:
              type: Point
              coordinates: [-74.006, 40.7128]
            properties:
              name: "New York"
              population: 8336817
          - type: Feature
            geometry:
              type: Point
              coordinates: [-118.243, 34.052]
            properties:
              name: "Los Angeles"
              population: 3979576
          - type: Feature
            geometry:
              type: Point
              coordinates: [-87.623, 41.881]
            properties:
              name: "Chicago"
              population: 2693976
    paint:
      circle-radius: 10
      circle-color: "#ef4444"
      circle-stroke-width: 2
      circle-stroke-color: "#ffffff"
    interactive:
      hover:
        cursor: pointer
      click:
        popup:
          - h3:
              - property: name
          - p:
              - str: "Population: "
              - property: population


controls:
  navigation: true
  scale: true
Complete example with interactive popups - click a city!

Next steps

Section titled “Next steps”

Now that you understand the basics, learn about: