Add custom marker icons with popups to a Leaflet map
Leaflet can show any image as a marker. In this code sample, we use pins generated by the Geoapify Marker Icon API as Leaflet markers and open a popup on click. The full code is on CodePen and in the quickstart examples on GitHub.
1. Build the icon URL
Design a marker in the Marker Icon API playground or set the parameters in code. You need an API key to use the icon in your project. Register for free, no credit card required.
function getMarkerIconUrl(place) {
const params = new URLSearchParams({
type: "awesome",
icon: place.icon, // a Font Awesome icon name, for example "paw"
color: place.color, // URLSearchParams encodes "#" as %23
contentColor: "#ffffff",
noWhiteCircle: "true",
size: "60", // height of the pin in CSS pixels, without the shadow
contentSize: "26",
scaleFactor: "2", // double-resolution PNG for sharp markers on retina screens
apiKey: myAPIKey
});
return `https://api.geoapify.com/v2/icon?${params}`;
}
2. Read the size and anchor from the response headers
The image includes the shadow, so it is taller than size, and the pin tip is not at the bottom edge. The Icon-Width, Icon-Height, Icon-Anchor-X, and Icon-Anchor-Y response headers give the display size and the tip position in CSS pixels. Request the image once with fetch(), read the headers, and reuse the image through a local URL:
async function loadMarker(url) {
const response = await fetch(url);
const header = (name) => Number(response.headers.get(name));
return {
width: header("Icon-Width"),
height: header("Icon-Height"),
anchorX: header("Icon-Anchor-X"),
anchorY: header("Icon-Anchor-Y"),
imageUrl: URL.createObjectURL(await response.blob())
};
}
For the zoo marker in this sample (type=awesome&size=60&scaleFactor=2), the headers are 46 × 67 px with the anchor at 23, 60.52.
![]()
3. Create the marker and its popup
iconSize is the display size from the headers; the PNG is twice as large because of scaleFactor=2. iconAnchor is the pixel Leaflet puts on the location. popupAnchor is relative to iconAnchor, so this one opens the popup just above the top of the pin. A popup can hold any HTML:
const marker = await loadMarker(getMarkerIconUrl(place));
const icon = L.icon({
iconUrl: marker.imageUrl,
iconSize: [marker.width, marker.height],
iconAnchor: [marker.anchorX, marker.anchorY],
popupAnchor: [marker.width / 2 - marker.anchorX, -marker.anchorY]
});
const popup = L.popup().setContent(`<strong>${place.title}</strong><br>${place.description}`);
L.marker([place.lat, place.lon], { icon, title: place.title }) // Leaflet uses [lat, lon]
.bindPopup(popup)
.addTo(map);

Rendered with Leaflet 1.9.4 on Geoapify osm-bright-grey raster tiles.
The sample shows three Munich places: Tierpark Hellabrunn, Marienplatz, and the Chinesischer Turm. The icons are from Font Awesome Free, so the map credits them in its attribution. See Shadows and map placement for other shadow styles, and How to Add Markers to a Map for MapLibre GL and OpenLayers.