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.

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.tsimport { 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],
],
];
} The React version uses the library's React adapter, cc-openlayers/react: each component creates the OpenLayers object it names when it mounts, updates it from its props and disposes of it when it unmounts.
overlay.react.tsximport {
CollectionCoordinates,
Coordinate,
DefaultControls,
DefaultInteractions,
Feature,
Map,
OSMSource,
Overlay as OLOverlay,
PolygonGeometry,
TileLayer,
VectorLayer,
VectorSource,
View,
} from 'cc-openlayers/react';
const area = [
[
[19.9353, 50.0605],
[19.9393, 50.0605],
[19.9393, 50.0629],
[19.9353, 50.0629],
[19.9353, 50.0605],
],
];
/** HTML content anchored to a map coordinate by an overlay that lets map events pass through. */
export function Overlay() {
return (
<Map height="480px">
<DefaultInteractions />
<DefaultControls />
<View zoom={16}>
<Coordinate x={19.9373} y={50.0617} srid="EPSG:4326" />
</View>
<TileLayer>
<OSMSource />
</TileLayer>
<VectorLayer>
<VectorSource>
<Feature>
<PolygonGeometry>
<CollectionCoordinates coordinates={area} srid="EPSG:4326" />
</PolygonGeometry>
</Feature>
</VectorSource>
</VectorLayer>
<OLOverlay positioning="center-center" stopEvent={false}>
<Coordinate x={19.9373} y={50.0617} srid="EPSG:4326" />
<span className="example-label">An HTML overlay anchored to the map</span>
</OLOverlay>
</Map>
);
}How the React version works
An HTML label stands in the middle of a rectangle by the Main Square. The overlay (Overlay) has stopEvent: false, so dragging and zooming also work over the label.
What both versions share
OpenLayers renders the map and handles the interactions; the cc-openlayers/core layer gives both adapters the same view binding (MapViewBinding) and the same conversion of coordinates from EPSG:4326 to the map's projection.
From Angular to React
| Angular | React |
|---|---|
<aol-overlay> with <aol-coordinate> and <aol-content> | <Overlay> with <Coordinate> and the content as children (imported as OLOverlay, because the name belongs to the example) |
<aol-collection-coordinates> in <aol-geometry-polygon> | <CollectionCoordinates> in <PolygonGeometry> |
Who creates, updates and disposes
Map creates the ol/Map in useLayoutEffect and disposes of it on unmount; each layer, source and interaction component adds its object to the parent it gets from context and removes it in its effect's cleanup, as ngOnDestroy does in Angular. Overlay renders its children through a portal into the overlay's element, so the content stays part of the React tree.
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-overlayanchors a live DOM element to the geographic position supplied by its childaol-coordinate.aol-contentprojects 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
stopEventat its default true blocks map drag-panning and wheel-zooming wherever the HTML badge covers the canvas—keepstopEventtrue only on interactive popups containing clickable buttons, inputs or selectable text. - Each
aol-overlaycreates 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.
Related examples
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.