MapSnippets logoMapSnippets logo

Add Markers and Popups in MapLibre GL JS

MapLibre GL JS

Place maplibregl.Marker instances on the map with clickable Popup overlays using MapLibre GL JS.

progress_activityLoading map...
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://api.maptiler.com/maps/streets-v4/style.json?key=YOUR_MAPTILER_KEY',
  center: [14.42, 50.08],
  zoom: 13
});
map.addControl(new maplibregl.NavigationControl());
const places = [
  { coords: [14.4205, 50.0875], name: 'Old Town Square', desc: 'Historic center of Prague' },
  { coords: [14.4006, 50.0904], name: 'Prague Castle', desc: 'Largest castle complex' },
  { coords: [14.4141, 50.0814], name: 'Charles Bridge', desc: 'Iconic Gothic bridge' }
];
places.forEach(p => {
  new maplibregl.Marker({ color: '#2196F3' })
    .setLngLat(p.coords)
    .setPopup(new maplibregl.Popup({ offset: 25 }).setHTML(`<b>${p.name}</b><br>${p.desc}`))
    .addTo(map);
});

How it works

MapLibre markers are DOM elements positioned on the map. Create a Marker with a color and position, then attach a Popup with HTML content. Markers are the simplest way to show a few points of interest.

Each marker sits in the DOM and updates its CSS position as the map moves. For up to ~100 markers this is fine. For hundreds or thousands of points, use a circle or symbol layer instead for GPU-rendered performance.

Popups open on click by default when attached via setPopup(). You can also show them on hover by listening to marker events.

Key APIs

API Description Docs
maplibregl.Marker DOM-based map marker maplibre.org docs
maplibregl.Popup Info popup attached to marker or coordinates maplibre.org docs
marker.setLngLat() Position the marker maplibre.org docs

FAQ

How do I use a custom icon instead of the default pin?

Pass an HTML element to the Marker constructor: new maplibregl.Marker({ element: myDiv }).

What is the performance limit for DOM markers?

Around 100-200 markers. Beyond that, switch to a circle or symbol layer for WebGL-rendered points.

Common mistakes

  • Using [lat, lng] instead of [lng, lat]: markers appear in the wrong location
  • Forgetting the offset on Popup: the popup overlaps the marker pin
  • Adding thousands of DOM markers: use layers for large datasets
auto_awesome

Build maps using MapLibre GL JS with AI

Generate code like this add markers and popups in maplibre gl js example using the MapLibre GL JS skill in your IDE.