Add custom HTML markers with popups and events to a MapLibre GL map

There are two ways to draw locations on a MapLibre GL map: as a layer or as separate markers. A MapLibre Marker is an HTML element, so you can style it with CSS and listen to any DOM event.

In this code sample, we add Geoapify Marker Icon API pins as markers, place them exactly with the response headers, and handle hover and click. The full code is on CodePen and in the quickstart examples on GitHub.

1. Get the marker image, its size, and its anchor

Design a marker in the Marker Icon API playground or set the parameters in code. Set scaleFactor=2 for sharp markers on high-density screens. Request the image once with fetch() and read its display size and pin-tip position from the Icon-* response headers:

const params = new URLSearchParams({
  type: "awesome", icon: "plane-departure", color: "#1e88e5",
  contentColor: "#ffffff", noWhiteCircle: "true",
  size: "52", contentSize: "22", scaleFactor: "2",
  apiKey: YOUR_API_KEY
});

const response = await fetch(`https://api.geoapify.com/v2/icon?${params}`);
const header = (name) => Number(response.headers.get(name));
const marker = {
  width: header("Icon-Width"),     // 40 for this marker
  height: header("Icon-Height"),   // 58: 52 px pin + shadow
  anchorX: header("Icon-Anchor-X"),
  anchorY: header("Icon-Anchor-Y"),
  imageUrl: URL.createObjectURL(await response.blob())
};

2. Add the marker

Create an <img> element at the display size from the headers. A MapLibre marker aligns one of nine named positions with the location, and none of them is the pin tip above a shadow. So put the image's top-left corner on the location and shift it back by the anchor:

const element = document.createElement("img");
element.src = marker.imageUrl;
element.alt = "Zürich Airport";
element.className = "place-marker";   // e.g. .place-marker { cursor: pointer; }
element.style.width = `${marker.width}px`;
element.style.height = `${marker.height}px`;

const airport = new maplibregl.Marker({
    element,
    anchor: "top-left",
    offset: [-marker.anchorX, -marker.anchorY]
  })
  .setLngLat([8.561162, 47.450893])   // MapLibre uses [lon, lat]
  .addTo(map);

MapLibre GL map of Zürich with three Geoapify Marker Icon API pins as HTML markers: a plane at Zürich Airport, a train at Zürich Hauptbahnhof, and a mountain at Uetliberg

Rendered with MapLibre GL 5.24.0 and the Geoapify osm-bright-grey vector style.

3. Create a popup above the pin

A popup is attached to the marker's coordinates, so move it up to the top of the pin. Set anchor: "bottom" to keep it above the pin: otherwise, near the top edge of the map, MapLibre flips the popup below the location, where it covers the marker.

const popup = new maplibregl.Popup({
  anchor: "bottom",
  offset: [marker.width / 2 - marker.anchorX, -marker.anchorY],
  closeButton: false
}).setText("Zürich Airport");

Use setText() or setHTML() for the content. To toggle a popup on click without custom code, attach it with airport.setPopup(popup).

4. Handle hover, click, and other events

MapLibre markers emit only drag events, but the element receives every DOM event. In this sample, hovering shows the popup and a click pins it open:

let pinned = false;

element.addEventListener("mouseenter", () => {
  if (!popup.isOpen()) {
    popup.setLngLat(airport.getLngLat()).addTo(map);
  }
});

element.addEventListener("mouseleave", () => {
  if (!pinned) {
    popup.remove();
  }
});

element.addEventListener("click", (event) => {
  event.stopPropagation();   // keep the click from reaching the map
  pinned = !pinned;
  popup.setHTML(pinned ? "<strong>Zürich Airport</strong><br>Pinned. Click again to unpin." : "Zürich Airport");
  if (!pinned) {
    popup.remove();
  }
});

The Zürich Hauptbahnhof marker after a click: an HTML popup above the pin reads "Zürich Hauptbahnhof — Pinned. Click again to unpin."

The sample shows Zürich Airport, Zürich Hauptbahnhof, and Uetliberg. The icons are from Font Awesome Free, so the map credits them in its attribution. See Shadows and map placement for other shadow styles.