MapSnippets logoMapSnippets logo

Custom Marker Icons with MapTiler SDK

MapTiler SDK

Create markers with custom HTML elements or SVG icons using the MapTiler SDK marker API.

progress_activityLoading map...
maptilersdk.config.apiKey = 'YOUR_MAPTILER_KEY';
const map = new maptilersdk.Map({
  container: 'map',
  style: maptilersdk.MapStyle.STREETS,
  center: [12.4964, 41.9028],
  zoom: 13
});
const makeSvgEl = (color) => {
  const el = document.createElement('div');
  el.innerHTML = `<svg width="30" height="40" viewBox="0 0 30 40" xmlns="http://www.w3.org/2000/svg"><path d="M15 0C6.7 0 0 6.7 0 15c0 11.3 15 25 15 25s15-13.7 15-25C30 6.7 23.3 0 15 0z" fill="${color}"/><circle cx="15" cy="14" r="6" fill="#fff"/></svg>`;
  el.style.cursor = 'pointer';
  return el;
};
new maptilersdk.Marker({ element: makeSvgEl('#9C27B0') })
  .setLngLat([12.4922, 41.8902])
  .setPopup(new maptilersdk.Popup({ offset: 25 }).setHTML('<b>Colosseum</b>'))
  .addTo(map);
const badgeEl = document.createElement('div');
badgeEl.style.cssText = 'background:#e63946;color:#fff;border-radius:50%;width:36px;height:36px;display:flex;align-items:center;justify-content:center;font-weight:bold;font-size:14px;border:2px solid #fff;cursor:pointer;';
badgeEl.textContent = 'V';
new maptilersdk.Marker({ element: badgeEl })
  .setLngLat([12.4534, 41.9029])
  .setPopup(new maptilersdk.Popup({ offset: 25 }).setHTML('<b>Vatican City</b>'))
  .addTo(map);

How it works

MapTiler SDK markers accept a custom element option that replaces the default pin with any HTML element. This lets you use inline SVGs, image tags, styled divs, or icon font characters. The custom element becomes the marker’s visual representation on the map.

The makeSvgEl() helper creates a pin-shaped SVG with a configurable color. The second marker uses a circular badge with a letter label. Both support popups through .setPopup() exactly like default markers. The element is positioned so its center aligns with the marker coordinates.

Key APIs

API Description Docs
maptilersdk.Marker({ element }) Marker with custom DOM element docs.maptiler.com/sdk-js/api/
maptilersdk.Popup Info popup attached to marker docs.maptiler.com/sdk-js/api/
.setLngLat() Position the marker docs.maptiler.com/sdk-js/api/

FAQ

How do I center a pin-shaped icon on the correct point?

By default the element’s center is placed at the coordinates. For a pin shape, use CSS transform: translateY(-50%) on the element or adjust the anchor option to bottom.

Can I change the icon dynamically after creation?

Yes. Since the marker holds a reference to your DOM element, modify its innerHTML or style at any time: the changes appear immediately on the map.

Common mistakes

  • Using [lat, lng] instead of [lng, lat]: MapTiler SDK follows GeoJSON coordinate order
  • Forgetting cursor: pointer on the custom element: the marker does not show a clickable cursor by default
  • Not setting maptilersdk.config.apiKey before creating the map: the map style fails to load
auto_awesome

Build maps using MapTiler SDK with AI

Generate code like this custom marker icons with maptiler sdk example using the MapTiler SDK skill in your IDE.

auto_awesomeGet skillskeyGet a free API key

Related Examples