DEV Community

Cover image for Step-by-Step: Leaflet Custom Marker with Geoapify Icons
Geoapify
Geoapify

Posted on

Step-by-Step: Leaflet Custom Marker with Geoapify Icons

#webdev #development #javascript #tutorial

Leaflet is a lightweight and powerful JavaScript library for building interactive maps. By default, Leaflet comes with simple map markers, but in many applications—especially those involving points of interest, events, or branding—you’ll want to customize how those markers look.

In this tutorial, you’ll learn how to create a Leaflet custom marker using the Geoapify Map Marker API. This API lets you generate unique, retina-ready marker icons on the fly—no image editing or asset hosting required.

We’ll walk through a complete working example, step by step, showing how to:

  • Set up a Leaflet map with custom Geoapify tiles.
  • Generate a marker icon dynamically with the Map Marker API.
  • Add the custom icon to the map with a popup.

Whether you’re building a travel app, a store locator, or just experimenting with maps, custom marker icons will help your design stand out.

Let’s get started!

Step 1: Set Up the Leaflet Map

Start by adding Leaflet to your page:

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>

<div id="my-map" style="height: 400px;"></div>
Enter fullscreen mode Exit fullscreen mode

Then initialize the map with Geoapify Map Tiles:

const map = L.map('my-map').setView([48.1500327, 11.5753989], 10);
const myAPIKey = "YOUR_GEOAPIFY_API_KEY";

const tileUrl = L.Browser.retina
  ? `https://maps.geoapify.com/v1/tile/osm-bright/{z}/{x}/{y}@2x.png?apiKey=${myAPIKey}`
  : `https://maps.geoapify.com/v1/tile/osm-bright/{z}/{x}/{y}.png?apiKey=${myAPIKey}`;

L.tileLayer(tileUrl, {
  attribution:
    'Powered by <a href="https://www.geoapify.com/" target="_blank">Geoapify</a> | © OpenStreetMap <a href="https://www.openstreetmap.org/copyright" target="_blank">contributors</a>',
  maxZoom: 20,
}).addTo(map);
Enter fullscreen mode Exit fullscreen mode

🔑 Get a free API key at Geoapify My Projects

Step 2: Generate a Custom Marker Icon with Geoapify

To create a unique marker icon, we'll use the Geoapify Map Marker API. This API lets you build marker icons dynamically using a URL with customizable parameters.

Here's an example of a pink marker with a green paw icon from Font Awesome:

const markerIcon = L.icon({
  iconUrl: `https://api.geoapify.com/v2/icon/?type=awesome&color=%23ffc3e8&size=60&icon=paw&contentSize=29&contentColor=%2334811a&noWhiteCircle&scaleFactor=2&apiKey=${myAPIKey}`,
  iconSize: [45, 66],
  iconAnchor: [22.5, 60],
  popupAnchor: [0, -62]
});
Enter fullscreen mode Exit fullscreen mode

Marker Icon API parameters used:

Parameter Description
apiKey Your Geoapify API key. Required.
type Marker style type. Options: material, awesome, circle, plain.
size Marker height in pixels (e.g., 60).
contentSize Size of the icon inside the marker (e.g., 29). Optional.
contentColor Color of the inner icon. Example: %2334811a (which is #34811a).
color Background color of the marker. Example: %23ffc3e8 (#ffc3e8).
iconType Icon library. Use awesome for Font Awesome or material for Material Icons.
icon Name of the icon (e.g., paw, star, coffee).
noWhiteCircle Removes the white circle behind the icon. Optional.
scaleFactor=2 Makes the icon retina-ready. Recommended.

Try customizing your marker by changing colors, icon names, or switching type=awesome to type=material to explore different styles.

Use the visual Icon API Playground to experiment with styles and generate your custom marker icon URL without writing code.

Understanding iconSize, iconAnchor, and popupAnchor

When creating a custom marker icon in Leaflet, it's important to define how the icon is positioned on the map. Here’s a breakdown of the options we used:

iconSize: [45, 66]

This defines the total size of the marker image (in pixels).

  • 45 is the width
  • 66 is the height Make sure these values match the actual dimensions of the PNG returned by the Map Marker API.

iconAnchor: [22.5, 60]

This sets the pixel coordinates where the marker "points" to the map.
In this case:

  • 22.5 is half of the width (centered horizontally)
  • 60 places the anchor near the bottom of the icon, so the tip touches the map

Without this, the marker would appear misaligned.

popupAnchor: [0, -62]

This determines where the popup opens relative to the iconAnchor.

  • 0 means it's centered horizontally
  • -62 shifts the popup up so it appears above the marker

Tweak this value if your marker is taller or shorter, to keep the popup nicely aligned.

Step 3: Adding a Marker to Leaflet

Now that we’ve created a custom marker icon, let’s add it to the map with a descriptive popup.

Use L.marker() to place the marker at specific coordinates, then attach a popup using bindPopup():

const zooMarkerPopup = L.popup().setContent(`
  <div class="popup-container">
    <h4 class="popup-title">Munich Zoo</h4>
    <div class="popup-address">
      <strong>Address:</strong><br/>
      Tierparkstraße 30<br/>
      81543 Munich<br/>
      Germany
    </div>
  </div>
`);

const zooMarker = L.marker([48.09698, 11.555466], {
  icon: markerIcon,
})
  .addTo(map)
  .bindPopup(zooMarkerPopup);
Enter fullscreen mode Exit fullscreen mode

What’s happening here:

  • L.marker([lat, lon], { icon }) places a marker at the Munich Zoo using the custom icon from the previous step.
  • L.popup().setContent(...) defines a rich HTML popup.
  • bindPopup() attaches the popup to the marker so it appears on click.

You can easily reuse this pattern for other points of interest—just update the coordinates, content, or icon!

Step 4: Live Demo and Summary

You can see the full working example in action here:

👉 Try the full demo on JSFiddle

This demo includes:

  • A Leaflet map with Geoapify tiles
  • A custom marker icon generated via the Geoapify Marker Icon API
  • A styled popup with address details

Summary

In this tutorial, you learned how to:

  • Set up a Leaflet map using Geoapify tiles
  • Generate a custom marker icon with the Map Marker API
  • Add the marker to the map with proper positioning and popup content

With Geoapify's icon generator and Leaflet’s flexibility, you can create clean, beautiful maps tailored to your app’s needs—no Photoshop or asset hosting required.

Useful links

Top comments (1)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.