Tile and image services · Angular, React and OpenLayers
Data under the pointer with UTFGrid
Inspect raster UTFGrid tile attributes on hover in OpenLayers and display labels in an HTML overlay while discarding stale pointer responses.

What this example shows
Moving the pointer across Central Europe queries an invisible companion attribute grid aligned with the raster map and positions a floating HTML callout directly beside the cursor whenever a feature is present underneath.
Sliding onto empty water or unmapped areas hides the overlay cleanly, and fast cursor sweeps ignore late asynchronous grid lookups from earlier positions.
When you need it
Pre-rendered raster tile pyramids carry zero DOM nodes or vector geometries of their own, yet thematic maps still need instant hover tooltips over thousands of polygons without downloading heavy GeoJSON payloads.
UTFGrid solves raster hit-testing by shipping compact JSON character-lookup grids per tile—letting low-powered devices resolve feature attributes under the cursor in constant time.
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.
utf-grid.tsimport { ChangeDetectionStrategy, Component, signal, viewChild } from '@angular/core';
import type { Coordinate } from 'ol/coordinate';
import {
ContentComponent,
ControlFullScreenComponent,
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerTileComponent,
MapComponent,
OverlayComponent,
SourceOsmComponent,
SourceUTFGridComponent,
ViewComponent,
} from 'cc-openlayers';
/** UTFGrid hover information: the label of the grid cell under the pointer, shown in an overlay. */
@Component({
selector: 'app-utf-grid',
imports: [
ContentComponent,
ControlFullScreenComponent,
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerTileComponent,
MapComponent,
OverlayComponent,
SourceOsmComponent,
SourceUTFGridComponent,
ViewComponent,
],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<aol-map height="480px" (pointerMove)="hover($event.coordinate)">
<aol-interaction-default />
<aol-control-defaults />
<aol-control-fullscreen />
<aol-view [zoom]="6"><aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" /></aol-view>
<aol-layer-tile><aol-source-osm /></aol-layer-tile>
<aol-layer-tile>
<aol-source-utfgrid url="/assets/utfgrid/tilejson.json" [preemptive]="false" />
</aol-layer-tile>
@if (info(); as detail) {
<aol-overlay positioning="bottom-right" [stopEvent]="false">
<aol-coordinate [x]="detail.coordinate[0]" [y]="detail.coordinate[1]" />
<aol-content
><span class="example-label">{{ detail.label }}</span></aol-content
>
</aol-overlay>
}
</aol-map>
`,
})
export class UtfGrid {
readonly info = signal<{ label: string; coordinate: Coordinate } | null>(null);
private readonly pointer = signal<Coordinate | null>(null);
private readonly grid = viewChild.required(SourceUTFGridComponent);
private readonly view = viewChild.required(ViewComponent);
protected hover(coordinate: Coordinate): void {
this.pointer.set(coordinate);
this.grid().instance.forDataAtCoordinateAndResolution(
coordinate,
this.view().instance.getResolution(),
(data: unknown) => {
if (this.pointer() !== coordinate) return;
const label = (data as { label?: unknown } | null)?.label;
this.info.set(typeof label === 'string' ? { label, coordinate } : null);
},
true
);
}
} 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.
utf-grid.react.tsximport { useRef, useState } from 'react';
import type { Coordinate as OLCoordinate } from 'ol/coordinate.js';
import type MapBrowserEvent from 'ol/MapBrowserEvent.js';
import type UTFGrid from 'ol/source/UTFGrid.js';
import type OLView from 'ol/View.js';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
FullScreenControl,
Map,
OSMSource,
Overlay,
TileLayer,
UTFGridSource,
View,
} from 'cc-openlayers/react';
/** UTFGrid hover information: the label of the grid cell under the pointer, shown in an overlay. */
export function UtfGrid() {
const [info, setInfo] = useState<{ label: string; coordinate: OLCoordinate } | null>(null);
const pointer = useRef<OLCoordinate | null>(null);
const grid = useRef<UTFGrid>(null);
const view = useRef<OLView>(null);
const hover = ({ coordinate }: MapBrowserEvent) => {
pointer.current = coordinate;
grid.current?.forDataAtCoordinateAndResolution(
coordinate,
view.current?.getResolution() as number,
(data: unknown) => {
if (pointer.current !== coordinate) return;
const label = (data as { label?: unknown } | null)?.label;
setInfo(typeof label === 'string' ? { label, coordinate } : null);
},
true
);
};
return (
<Map height="480px" onPointerMove={hover}>
<DefaultInteractions />
<DefaultControls />
<FullScreenControl />
<View ref={view} zoom={6}>
<Coordinate x={19.9368} y={50.0614} srid="EPSG:4326" />
</View>
<TileLayer>
<OSMSource />
</TileLayer>
<TileLayer>
<UTFGridSource ref={grid} url="/assets/utfgrid/tilejson.json" preemptive={false} />
</TileLayer>
{info ? (
<Overlay positioning="bottom-right" stopEvent={false}>
<Coordinate x={info.coordinate[0]} y={info.coordinate[1]} />
<span className="example-label">{info.label}</span>
</Overlay>
) : null}
</Map>
);
}How the React version works
Under the cursor an overlay shows the label of the UTFGrid cell; a late answer for a place the cursor has already left is ignored.
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 |
|---|---|
(pointerMove)="hover($event.coordinate)" | onPointerMove={hover} |
a signal with the last cursor position | useRef, because it is only compared in the callback and does not affect the view |
<aol-overlay> with @if | {info ? <Overlay …> : null} |
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
aol-source-utfgrid reads a TileJSON descriptor pointing at the UTFGrid pyramid and exposes forDataAtCoordinateAndResolution. Because grid tiles may still be downloading when the pointer first enters a region, the lookup invokes its callback asynchronously; comparing the callback’s target coordinate against the latest pointer state prevents out-of-order responses from overwriting the current tooltip.
When non-null attribute data with a label arrives, aol-overlay and aol-coordinate anchor the HTML badge at the cursor coordinate, while @if removes it cleanly over empty cells.
How it works
aol-source-utfgridparses the TileJSON grid configuration and resolves pointer attributes viaforDataAtCoordinateAndResolution.- Stale asynchronous callbacks are discarded whenever the pointer has already moved away from the queried coordinate.
aol-overlaypaired withaol-coordinatepositions the tooltip at the cursor, and@ifunmounts it when no feature is hit.- Records lacking a display label clear any previously shown tooltip immediately.
Pitfalls
- Never apply asynchronous UTFGrid callback payloads unconditionally: over slow connections, an older tile response arriving late will flash the wrong region’s label at the new cursor spot.
- UTFGrid sources pass
nullto the callback over empty background pixels—treatnullas normal empty space rather than a failure state.
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.