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.

A map of Central Europe with the label Sample feature · local UTFGrid data next to the pointer.
A screenshot of the example. UTFGrid: a local sample tile. Map data © OpenStreetMap contributors.

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

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-utfgrid parses the TileJSON grid configuration and resolves pointer attributes via forDataAtCoordinateAndResolution.
  • Stale asynchronous callbacks are discarded whenever the pointer has already moved away from the queried coordinate.
  • aol-overlay paired with aol-coordinate positions the tooltip at the cursor, and @if unmounts 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 null to the callback over empty background pixels—treat null as normal empty space rather than a failure state.

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.