Add HTML markers to the map

This article shows you how to add a custom HTML such as an image file to the map as an HTML Marker.


HTML Markers do not connect to data sources. Instead position information is added directly to the marker and the marker is added to the maps markers property which is a HtmlMarkerManager.


Unlike most layers in the Azure Maps Web control which use WebGL for rendering, HTML Markers use traditional DOM elements for rendering. As such, the more HTML markers added to a page, the more DOM elements there are. Performance can degrade after adding a few hundred HTML markers. For larger data sets consider either clustering your data or using a Symbol or Bubble layer.

Add an HTML marker

The HtmlMarker class has a default style. You can customize the marker by setting the color and text options of the marker. The default style of the HTML marker class is an SVG template that has a {color} and {text} placeholder. Set the color and text properties in the HTML marker options for a quick customization.

The following code creates an HTML marker, and sets the color property to "DodgerBlue" and the text property to "10". A popup is attached to the marker and click event is used to toggle the visibility of the popup.

//Create an HTML marker and add it to the map.
var marker = new atlas.HtmlMarker({
    color: 'DodgerBlue',
    text: '10',
    position: [0, 0],
    popup: new atlas.Popup({
        content: '<div style="padding:10px">Hello World</div>',
        pixelOffset: [0, -30]


//Add a click event to toggle the popup.'click',marker, () => {

Below is the complete running code sample of the above functionality.

Create SVG templated HTML marker

The default htmlContent of an Html marker is an SVG template with place folders {color} and {text} in it. You can create custom SVG strings and add these same placeholders into your SVG such that setting the color and text options of the marker update these placeholders in your SVG.


The Azure Maps web SDK provides several SVG image templates that can be used with HTML markers. For more information, see the How to use image templates document.

Add a CSS styled HTML marker

One of the benefits of HTML markers is that there are many great customizations that can be achieved using CSS. In this sample, the content of the HtmlMarker consists of HTML and CSS that create an animated pin that drops into place and pulses.

Draggable HTML markers

This sample shows how to make an HTML marker draggable. HTML markers support drag, dragstart, and dragend events.

Add mouse events to HTML markers

These samples show how to add mouse and drag events to an HTML marker.

Next steps

Learn more about the classes and methods used in this article:

For more code examples to add to your maps, see the following articles: