Overlays and animation · Angular, React and OpenLayers
A tooltip that follows the pointer
Follow the pointer with a non-blocking HTML hover tooltip naming Polish voivodeships in OpenLayers while supporting touch taps and UI controls.

What this example shows
Over a clean categorical map of Poland’s 16 voivodeships, gliding the mouse smoothly carries a compact dark tooltip (małopolskie, śląskie, ...) 8 pixels above the cursor tip—hiding automatically during map drag gestures, over map control buttons, or when the pointer exits the canvas, and appearing on tap for touch screens.
When you need it
Choropleth maps, statistical districts and thematic heat zones are fastest to scan when values float right beside the user’s eye without requiring clicks or dedicating sidebar width.
Combining non-blocking pointer passthrough with control-element filtering and touch fallback makes hover tooltips feel effortless across desktop and mobile.
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.
tooltip-on-hover.tsimport { ChangeDetectionStrategy, Component, signal, viewChild } from '@angular/core';
import {
ContentComponent,
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerVectorComponent,
MapComponent,
OverlayComponent,
SourceGeoJSONComponent,
ViewComponent,
} from 'cc-openlayers';
import type { Coordinate } from 'ol/coordinate';
import type { FeatureLike } from 'ol/Feature';
import type MapBrowserEvent from 'ol/MapBrowserEvent';
import Fill from 'ol/style/Fill';
import Style from 'ol/style/Style';
/** The colour of each voivodeship, by its position in code order. */
const PALETTE = [
'#4e79a7',
'#f28e2b',
'#e15759',
'#76b7b2',
'#59a14f',
'#edc948',
'#b07aa1',
'#ff9da7',
'#9c755f',
'#bab0ac',
'#86bcb6',
'#d37295',
'#fabfd2',
'#b6992d',
'#499894',
'#79706e',
];
/** A tooltip with the name of the voivodeship under the pointer, an overlay that follows the pointer. */
@Component({
selector: 'app-tooltip-on-hover',
imports: [
ContentComponent,
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerVectorComponent,
MapComponent,
OverlayComponent,
SourceGeoJSONComponent,
ViewComponent,
],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<aol-map height="480px" (pointerMove)="hover($event)" (olClick)="show($event)" (pointerleave)="hide()">
<aol-interaction-default />
<aol-control-defaults />
<aol-view [zoom]="6"><aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" /></aol-view>
<aol-layer-vector background="white" [style]="colorStyle">
<aol-source-geojson url="assets/poland/voivodeships.geojson" featureProjection="EPSG:3857" />
</aol-layer-vector>
<aol-overlay positioning="bottom-center" [offset]="[0, -8]" [stopEvent]="false">
<aol-coordinate [x]="position()[0]" [y]="position()[1]" />
<aol-content>
@if (name()) {
<span class="example-label">{{ name() }}</span>
}
</aol-content>
</aol-overlay>
</aol-map>
`,
})
export class TooltipOnHover {
readonly name = signal('');
readonly position = signal<Coordinate>([0, 0]);
protected readonly colorStyle = (feature: FeatureLike) =>
new Style({ fill: new Fill({ color: PALETTE[Number(feature.get('code')) / 2 - 1] ?? '#eeeeee' }) });
private readonly map = viewChild.required(MapComponent);
protected hover(event: MapBrowserEvent): void {
if (event.dragging) this.hide();
else this.show(event);
}
protected show(event: MapBrowserEvent): void {
const target = event.originalEvent.target as Element | null;
const feature = target?.closest('.ol-control')
? undefined
: this.map().instance.forEachFeatureAtPixel(event.pixel, (hit) => hit);
if (!feature) return this.hide();
this.position.set(event.coordinate);
this.name.set(feature.get('name'));
}
protected hide(): void {
this.name.set('');
}
} 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.
tooltip-on-hover.react.tsximport { useRef, useState } from 'react';
import type { Coordinate as OLCoordinate } from 'ol/coordinate.js';
import type { FeatureLike } from 'ol/Feature.js';
import type OLMap from 'ol/Map.js';
import type MapBrowserEvent from 'ol/MapBrowserEvent.js';
import Fill from 'ol/style/Fill.js';
import Style from 'ol/style/Style.js';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
GeoJSONSource,
Map,
Overlay,
VectorLayer,
View,
} from 'cc-openlayers/react';
/** The colour of each voivodeship, by its position in code order. */
const PALETTE = [
'#4e79a7',
'#f28e2b',
'#e15759',
'#76b7b2',
'#59a14f',
'#edc948',
'#b07aa1',
'#ff9da7',
'#9c755f',
'#bab0ac',
'#86bcb6',
'#d37295',
'#fabfd2',
'#b6992d',
'#499894',
'#79706e',
];
const colorStyle = (feature: FeatureLike) =>
new Style({ fill: new Fill({ color: PALETTE[Number(feature.get('code')) / 2 - 1] ?? '#eeeeee' }) });
const OFFSET = [0, -8];
/** A tooltip with the name of the voivodeship under the pointer, an overlay that follows the pointer. */
export function TooltipOnHover() {
const [name, setName] = useState('');
const [position, setPosition] = useState<OLCoordinate>([0, 0]);
const map = useRef<OLMap>(null);
const hide = () => setName('');
const show = (event: MapBrowserEvent) => {
const target = event.originalEvent.target as Element | null;
const feature = target?.closest('.ol-control')
? undefined
: map.current?.forEachFeatureAtPixel(event.pixel, (hit) => hit);
if (!feature) return hide();
setPosition(event.coordinate);
setName(feature.get('name'));
};
const hover = (event: MapBrowserEvent) => {
if (event.dragging) hide();
else show(event);
};
// Angular listens for pointerleave on the map's host element; in React the map gets a wrapper for it.
return (
<div onPointerLeave={hide}>
<Map ref={map} height="480px" onPointerMove={hover} onClick={show}>
<DefaultInteractions />
<DefaultControls />
<View zoom={6}>
<Coordinate x={19.9368} y={50.0614} srid="EPSG:4326" />
</View>
<VectorLayer background="white" style={colorStyle}>
<GeoJSONSource url="assets/poland/voivodeships.geojson" featureProjection="EPSG:3857" />
</VectorLayer>
<Overlay positioning="bottom-center" offset={OFFSET} stopEvent={false}>
<Coordinate x={position[0]} y={position[1]} />
{name ? <span className="example-label">{name}</span> : null}
</Overlay>
</Map>
</div>
);
}How the React version works
A tooltip with the name of the voivodeship under the pointer appears above it; it disappears while the map is dragged, over the controls and when the pointer leaves the map. A click shows it too, which helps on touch screens.
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. The palette of voivodeship colours by code and the style function are the same in both versions.
From Angular to React
| Angular | React |
|---|---|
(pointerMove), (olClick) on aol-map | onPointerMove, onClick on Map |
(pointerleave)="hide()" on the aol-map element | <div onPointerLeave={hide}> around Map: Angular listens to a DOM event on the component's host element, while React's Map takes no DOM events, so the example adds an element that receives them |
viewChild.required(MapComponent).instance.forEachFeatureAtPixel | map.current?.forEachFeatureAtPixel through the ref |
@if (name()) in aol-content | {name ? <span …> : null} in Overlay |
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.
Architecture and OpenLayers mechanics
(pointerMove) calls hover, immediately hiding the tooltip while event.dragging is true and otherwise querying forEachFeatureAtPixel (ignoring events over .ol-control via closest('.ol-control') in show).
The position signal updates aol-coordinate on the aol-overlay (positioning="bottom-center", [offset]="[0, -8]"), [stopEvent]="false" ensures wheel zoom and drag-pan presses pass straight through the badge, (olClick) supports hoverless touch devices, and (pointerleave) hides the badge on exit.
How it works
(pointerMove)invokeshover, suppressing tooltips mid-drag (event.dragging) and resolving features viaforEachFeatureAtPixel.- Updating
positionmoves theaol-overlay(positioning="bottom-center",[offset]="[0, -8]") smoothly above the cursor. [stopEvent]="false"keeps mouse-wheel zooming and drag panning completely unobstructed underneath the floating label.closest('.ol-control')insideshowsuppresses tooltips when hovering over zoom or attribution buttons.
Pitfalls
- Smartphones and tablets have no passive mouse hover—wire
(olClick)alongside(pointerMove)so tapping a region reveals the same tooltip. - Always clear tooltip state on
(pointerleave), otherwise the last hovered region badge remains stranded near the map border after the cursor leaves.
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.