MapMetrics Atlas API Docs

Appearance

Display a Popup ​

Show a popup with custom HTML at a specific map location, or trigger it from a marker or click event.

Basic Popup ​

javascript
const popup = new mapmetricsgl.Popup({ closeButton: true, closeOnClick: true })
  .setLngLat([2.3499, 48.853])
  .setHTML('<strong>Paris</strong><br/>Capital of France')
  .addTo(map);

// Remove programmatically
popup.remove();
javascript
new mapmetricsgl.Popup({
  closeButton: true,      // Show × button (default: true)
  closeOnClick: true,     // Close when map is clicked (default: true)
  anchor: 'bottom',       // Anchor: 'top' | 'bottom' | 'left' | 'right' | 'center'
  offset: [0, -10],       // Pixel offset [x, y]
  maxWidth: '300px',      // Max popup width
})

Popup with Text vs HTML ​

javascript
// Plain text (safe, auto-escaped)
popup.setText('Hello World');

// HTML content
popup.setHTML('<strong>Title</strong><p>Description</p>');

// Set coordinates
popup.setLngLat([lng, lat]);

Attach Popup to Marker ​

javascript
const marker = new mapmetricsgl.Marker()
  .setLngLat([2.3499, 48.853])
  .setPopup(
    new mapmetricsgl.Popup().setHTML('<strong>Paris</strong>')
  )
  .addTo(map);

// Open/close programmatically
marker.togglePopup();
javascript
map.on('click', 'my-layer', (e) => {
  const feature = e.features[0];
  new mapmetricsgl.Popup()
    .setLngLat(e.lngLat)
    .setHTML(`<strong>${feature.properties.name}</strong>`)
    .addTo(map);
});

Complete Example ​

html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <link href="https://cdn.mapmetrics-atlas.net/versions/latest/mapmetrics-gl.css" rel="stylesheet" />
    <script src="https://cdn.mapmetrics-atlas.net/versions/latest/mapmetrics-gl.js"></script>
    <style>#map { height: 500px; width: 100%; }</style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      const map = new mapmetricsgl.Map({
        container: 'map',
        style: '<StyleFile_URL_with_Token>',
        center: [2.3499, 48.853],
        zoom: 5
      });

      map.on('load', () => {
        // Show popup at a location
        new mapmetricsgl.Popup({ closeButton: true })
          .setLngLat([2.3499, 48.853])
          .setHTML('<strong>Paris</strong><br/>Capital of France')
          .addTo(map);

        // Popup on map click
        map.on('click', (e) => {
          new mapmetricsgl.Popup()
            .setLngLat(e.lngLat)
            .setHTML(`Lng: ${e.lngLat.lng.toFixed(4)}, Lat: ${e.lngLat.lat.toFixed(4)}`)
            .addTo(map);
        });
      });
    </script>
  </body>
</html>
jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const DisplayPopup = () => {
  const mapContainer = useRef(null);
  const map = useRef(null);
  const popup = useRef(null);

  useEffect(() => {
    if (map.current) return;
    map.current = new mapmetricsgl.Map({
      container: mapContainer.current,
      style: '<StyleFile_URL_with_Token>',
      center: [2.3499, 48.853],
      zoom: 5
    });

    map.current.on('load', () => {
      // Show popup at a fixed location
      popup.current = new mapmetricsgl.Popup({ closeButton: true })
        .setLngLat([2.3499, 48.853])
        .setHTML('<strong>Paris</strong><br/>Capital of France')
        .addTo(map.current);

      // Popup on click
      map.current.on('click', (e) => {
        if (popup.current) popup.current.remove();
        popup.current = new mapmetricsgl.Popup()
          .setLngLat(e.lngLat)
          .setHTML(`Lng: ${e.lngLat.lng.toFixed(4)}, Lat: ${e.lngLat.lat.toFixed(4)}`)
          .addTo(map.current);
      });
    });

    return () => { map.current?.remove(); map.current = null; };
  }, []);

  return <div ref={mapContainer} style={{ height: '500px', width: '100%' }} />;
};

export default DisplayPopup;

For more information, visit the MapMetrics GitHub repository.