Display a popup on hover

Replicates the MapLibre example Display a popup on hover. The upstream version tracks mousemove/mouseleave by hand, creates a Popup({ closeButton: false, closeOnClick: false }), and dedupes so the popup doesn’t flicker on every mouse move; here that whole dance is one hover.popup entry.

Hover a point for a preview; click to pin it

The complete document

display-a-popup-on-hover.yaml

# yaml-language-server: $schema=https://docs.maplibre-yaml.org/schema/latest/map.schema.json
# Gallery twin of https://maplibre.org/maplibre-gl-js/docs/examples/display-a-popup-on-hover/
# The mousemove/mouseleave handler dance is one `hover.popup` entry: shown
# chromeless while hovering, dismissed on leave, deduped per feature. A click
# pins the popup (with a close button) and suppresses hover until dismissed.
type: map
id: display-a-popup-on-hover
config:
  center: [-100.04, 38.907]
  zoom: 3
  mapStyle: "https://demotiles.maplibre.org/style.json"
layers:
  - id: places
    type: circle
    source:
      type: geojson
      generateId: true
      data:
        type: FeatureCollection
        features:
          - type: Feature
            geometry: { type: Point, coordinates: [-77.032, 38.913] }
            properties:
              title: Washington DC
              description: The nation's capital
          - type: Feature
            geometry: { type: Point, coordinates: [-122.414, 37.776] }
            properties:
              title: San Francisco
              description: Fog, hills, and sourdough
          - type: Feature
            geometry: { type: Point, coordinates: [-87.65, 41.84] }
            properties:
              title: Chicago
              description: The city of big shoulders
    paint:
      circle-radius: 8
      circle-color: "#2a6f97"
      circle-stroke-width: 2
      circle-stroke-color: "#ffffff"
    interactive:
      hover:
        cursor: pointer
        popup:
          - h3:
              - property: title
          - p:
              - property: description
      click:
        popup:
          - h3:
              - property: title
          - p:
              - property: description

What to notice

• The hover popup is chromeless (no close button) and dismisses when the pointer leaves the layer — it’s a preview, not a commitment.
• Hover previews, click pins. With both hover.popup and click.popup on one layer, clicking pins the popup (close button included) and hover previews are suppressed until you dismiss it.
• Popups show once per feature entered, not per mouse move — the per-feature dedupe the upstream example hand-rolls.
• Touch has no hover: on touch devices a tap opens the click.popup, so no content is hover-only.
• generateId: true on the source gives features ids for exact dedupe tracking; without ids the popup still works, keyed by geometry (with a console hint).