Quick start: a map in an HTML page

In this tutorial you make a web page with a map of the past week’s earthquakes, from two files: an HTML page and a YAML file that describes the map. Nothing is installed: the page loads maplibre-yaml from a CDN. You need a text editor and Node.js, for a local web server.

To try the format before you make any files, open the same map in the playground: edit it in the browser and the map changes as you type.

1. Create an HTML file

Make a new folder for the map. In it, create a file called index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <!-- Without this line, phones lay the page out at desktop width and the map looks tiny -->
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>My first map</title>
    <link
      href="https://unpkg.com/maplibre-gl@6/dist/maplibre-gl.css"
      rel="stylesheet"
    />
    <!-- Tell the browser where to find maplibre-gl -->
    <script type="importmap">
      { "imports": { "maplibre-gl": "https://unpkg.com/maplibre-gl@6/dist/maplibre-gl.mjs" } }
    </script>
    <!-- Register the <ml-map> element -->
    <script
      type="module"
      src="https://unpkg.com/@maplibre-yaml/core@0.10/register.js"
    ></script>
    <style>
      body {
        margin: 0;
      }
      /* <ml-map> has no size of its own: without a height the map is invisible */
      ml-map {
        display: block;
        width: 100%;
        height: 100vh;
      }
    </style>
  </head>
  <body>
    <ml-map src="./map.yaml"></ml-map>
  </body>
</html>

The page loads MapLibre’s stylesheet, tells the browser where MapLibre is, loads the script that defines the <ml-map> element, and gives the map the whole window. <ml-map src="./map.yaml"> is the map.

2. Describe the map in YAML

In the same folder, create a file called map.yaml. This file is the map document:

type: map              # this file describes one map
id: earthquake-map     # a short name for it, in your own words
config:                # the view the map opens on
  center: [-120, 37]   # [longitude, latitude]: California
  zoom: 4              # 0 is the whole world; higher numbers zoom in
  mapStyle: "https://tiles.openfreemap.org/styles/liberty"  # the basemap
layers:                # your data, drawn on top of the basemap
  - id: earthquakes
    type: circle       # draw each point as a circle
    source:            # where the points come from
      type: geojson
      url: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson"
    paint:             # how the circles look
      circle-radius: 6
      circle-color: "#e74c3c"
      circle-stroke-width: 1
      circle-stroke-color: "#ffffff"

Two YAML rules trip up almost everyone the first time: indent with spaces, never tabs, and put colours in quotes. circle-color: #e74c3c without quotes is empty, because # starts a comment in YAML.

3. Run a local server

In the folder that holds both files, run:

npx serve .

Open the address it prints (usually http://localhost:3000) in your browser. Double-clicking index.html instead doesn’t work: a page opened from a file:// address isn’t allowed to fetch map.yaml.

Result

You see this map, with every earthquake of the past seven days as a red dot. Drag to pan; scroll or pinch to zoom.

Earthquakes of the past seven days, from the USGS live feed

Edit this map in the playground

Make each earthquake clickable: add the interactive: block (the highlighted lines) to the layer in map.yaml, save, and reload the page.

type: map
id: earthquake-map
config:
  center: [-120, 37]
  zoom: 4
  mapStyle: "https://tiles.openfreemap.org/styles/liberty"
layers:
  - id: earthquakes
    type: circle
    source:
      type: geojson
      url: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson"
    paint:
      circle-radius: 6
      circle-color: "#e74c3c"
      circle-stroke-width: 1
      circle-stroke-color: "#ffffff"
    interactive:
      hover:
        cursor: pointer
      click:
        popup:
          - h3:
              - property: title

hover: turns the pointer into a hand over a dot. click: opens a popup whose heading (h3) is the earthquake’s title property from the data, such as M 2.1 - 10 km NE of Aguanga, CA. The popups guide shows what else a popup can hold.

Click an earthquake to see its title