Skip to main content

Display popups

Last updated: September 25, 2026 | 3 minutes read

A popup is an HTML element anchored to a coordinate on the map. It follows its coordinate while the map is panned, zoomed or rotated, which makes it a good fit for showing details about a landmark, a marker or any other location the user selected.

Show a popup​

Use the showPopup method of GemMap, providing the coordinate and the content. The content can be an HTML string or an HTMLElement:

import { Coordinates } from '@magiclane/maps-sdk';

const popup = gemMap.showPopup(
  new Coordinates({ latitude: 48.8584, longitude: 2.2945 }),
  '<strong>Eiffel Tower</strong><br/>Champ de Mars, Paris'
);

By default the popup sits above the coordinate, with its bottom edge pointing at it, and shows a close button. Several popups can be open at the same time.

warning

String content is inserted as HTML. Sanitize any text that comes from users or external sources before passing it to showPopup, or build an HTMLElement and set its textContent instead.

const content = document.createElement('div');
content.textContent = landmark.name; // Safe for any text

gemMap.showPopup(landmark.coordinates, content);

The third parameter of showPopup is a PopupOptions object:

OptionTypeDefaultDescription
anchor'center', 'top', 'bottom', 'left', 'right', 'top-left', 'top-right', 'bottom-left', 'bottom-right''bottom'Which side of the popup points at the coordinate.
offsetnumber0Distance in pixels between the coordinate and the popup.
closeButtonbooleantrueShows a close button in the popup.
closeOnClickbooleantrueCloses the popup when the user presses on the map.
maxWidthstring'260px'CSS maximum width of the popup body.
classNamestring-Additional CSS class name added to the popup container, for custom styling.
gemMap.showPopup(coordinates, '<b>Drop-off point</b>', {
  anchor: 'left',
  offset: 12,
  closeOnClick: false,
  className: 'my-popup',
});

Update and close a popup​

showPopup returns a Popup object that can be used to update or close the popup later:

import { Coordinates } from '@magiclane/maps-sdk';

// Replace the content
popup.setContent('<strong>Updated</strong>');

// Move the popup to another coordinate
popup.setCoordinates(new Coordinates({ latitude: 48.8606, longitude: 2.3376 }));

// Close the popup
if (popup.isOpen) {
  popup.close();
}

// Close all popups opened with showPopup
gemMap.closeAllPopups();

Show a popup for a selected landmark​

Popups are often combined with map selection. The following example opens a popup for the landmark the user tapped:

import { Landmark, Point } from '@magiclane/maps-sdk';

gemMap.registerTouchCallback(async (point: Point) => {
  await gemMap.setCursorScreenPosition(point);
  const landmarks: Landmark[] = gemMap.cursorSelectionLandmarks();

  if (landmarks.length === 0) {
    return;
  }

  const content = document.createElement('div');
  content.textContent = landmarks[0].name;

  gemMap.showPopup(landmarks[0].coordinates, content);
});
note

Pressing on the map closes the popups opened with closeOnClick set to true, so only the popup for the latest selection stays open. Presses on a popup itself do not close it.

Last updated on