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.

Poland's voivodeships in flat colours on a white background, and the dark tooltip małopolskie just above the pointer, which rests on Kraków.
A screenshot of the example. Voivodeships: Państwowy Rejestr Granic © GUGiK.

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.ts
import { 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('');
  }
}

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) invokes hover, suppressing tooltips mid-drag (event.dragging) and resolving features via forEachFeatureAtPixel.
  • Updating position moves the aol-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') inside show suppresses 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.

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.