Overlays and animation · Angular, React and OpenLayers

An HTML overlay on the map

Anchor live Angular or React HTML markup directly to a WGS84 map coordinate in OpenLayers using aol-overlay, positioning and stopEvent false.

Kraków's Main Square with a rectangle around it and the dark label An HTML overlay anchored to the map in its middle.
A screenshot of the example. Map data © OpenStreetMap contributors.

What this example shows

Centred on Kraków’s Main Square inside a reference rectangle, a styled dark HTML badge (An HTML overlay anchored to the map) stays locked precisely to its geographic coordinate as you pan, zoom and rotate the map—while allowing mouse drags starting right on top of the badge to pan the map normally.

When you need it

Interactive callouts containing links, buttons, rich CSS flex/grid layouts, status pills or live Angular/React components are far easier and more accessible to build in HTML than in 2D canvas text commands.

OpenLayers’ Overlay translates geographic coordinates to CSS transforms on every render frame so standard DOM elements ride smoothly on top of the map canvas.

The code

The example uses cc-openlayers, my Angular component library for OpenLayers: each aol-… element creates the OpenLayers object it names, updates it from its inputs and disposes of it with the component.

overlay.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
  CollectionCoordinatesComponent,
  ContentComponent,
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  FeatureComponent,
  GeometryPolygonComponent,
  LayerTileComponent,
  LayerVectorComponent,
  MapComponent,
  OverlayComponent,
  SourceOsmComponent,
  SourceVectorComponent,
  ViewComponent,
} from 'cc-openlayers';

/** HTML content anchored to a map coordinate by an overlay that lets map events pass through. */
@Component({
  selector: 'app-overlay',
  imports: [
    CollectionCoordinatesComponent,
    ContentComponent,
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    FeatureComponent,
    GeometryPolygonComponent,
    LayerTileComponent,
    LayerVectorComponent,
    MapComponent,
    OverlayComponent,
    SourceOsmComponent,
    SourceVectorComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-view [zoom]="16">
        <aol-coordinate [x]="19.9373" [y]="50.0617" srid="EPSG:4326" />
      </aol-view>
      <aol-layer-tile><aol-source-osm /></aol-layer-tile>
      <aol-layer-vector>
        <aol-source-vector>
          <aol-feature>
            <aol-geometry-polygon>
              <aol-collection-coordinates [coordinates]="area" srid="EPSG:4326" />
            </aol-geometry-polygon>
          </aol-feature>
        </aol-source-vector>
      </aol-layer-vector>
      <aol-overlay positioning="center-center" [stopEvent]="false">
        <aol-coordinate [x]="19.9373" [y]="50.0617" srid="EPSG:4326" />
        <aol-content><span class="example-label">An HTML overlay anchored to the map</span></aol-content>
      </aol-overlay>
    </aol-map>
  `,
})
export class Overlay {
  protected readonly area = [
    [
      [19.9353, 50.0605],
      [19.9393, 50.0605],
      [19.9393, 50.0629],
      [19.9353, 50.0629],
      [19.9353, 50.0605],
    ],
  ];
}

Architecture and OpenLayers mechanics

aol-overlay pairs an aol-coordinate (accepting WGS84 degrees) with an aol-content projection wrapper so full Angular/React data binding, styling and accessibility work inside the overlay node.

positioning="center-center" aligns the midpoint of the HTML element directly over the coordinate, and [stopEvent]="false" places the overlay in the event-passthrough container so drags and wheel zooms pass through to the map.

How it works

  • aol-overlay anchors a live DOM element to the geographic position supplied by its child aol-coordinate.
  • aol-content projects component template HTML into OpenLayers’ overlay container with live framework bindings intact.
  • positioning="center-center" centres the badge both horizontally and vertically over the target coordinate.
  • [stopEvent]="false" allows pointer drags and wheel events over the badge to reach the underlying map.

Pitfalls

  • Leaving stopEvent at its default true blocks map drag-panning and wheel-zooming wherever the HTML badge covers the canvas—keep stopEvent true only on interactive popups containing clickable buttons, inputs or selectable text.
  • Each aol-overlay creates real DOM nodes repositioned every frame: use overlays for a handful of callouts or active popups, and switch to canvas vector Text / Icon styles when rendering hundreds or thousands of labels.

The same feature in the OpenLayers examples .

Background: state and lifecycle of maps in Angular with OpenLayers, which the components of cc-openlayers take care of.