Layers · Angular, React and OpenLayers
Render vector data as an image
Accelerate dense polygon panning in OpenLayers with VectorImageLayer, a 2x imageRatio buffer and hit-detected hover highlights in Angular.

What this example shows
Poland’s 16 voivodeship polygons—with thousands of detailed border vertices—render in a 16-colour categorical palette over a dark navy background at zoom 7. Dragging and zooming stay effortlessly fluid because polygons are rasterised once into an off-screen image that glides across frames.
Hovering with a mouse (or tapping on touch screens) still identifies the exact voivodeship beneath the pointer, outlines its border in crisp white and displays its name below the map.
When you need it
Choropleth maps of municipalities, soil polygons, cadastral zones or Natura 2000 habitats can bog down 60 fps panning when a standard VectorLayer re-strokes tens of thousands of vertices on every intermediate drag frame.
VectorImageLayer gives you the best of both worlds: static-image pan speed during camera motion plus full client-side vector hit detection and dynamic styling once settled.
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.
image-vector-layer.tsimport { ChangeDetectionStrategy, Component, signal, viewChild } from '@angular/core';
import {
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerVectorComponent,
LayerVectorImageComponent,
MapComponent,
SourceGeoJSONComponent,
SourceVectorComponent,
StyleComponent,
StyleStrokeComponent,
ViewComponent,
} from 'cc-openlayers';
import type Feature from 'ol/Feature';
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',
];
/** The voivodeships rendered as one image by a vector image layer; the one under the pointer is outlined and named. */
@Component({
selector: 'app-image-vector-layer',
imports: [
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerVectorComponent,
LayerVectorImageComponent,
MapComponent,
SourceGeoJSONComponent,
SourceVectorComponent,
StyleComponent,
StyleStrokeComponent,
ViewComponent,
],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<aol-map height="480px" (pointerMove)="move($event)" (olClick)="showFeatureInfo($event)">
<aol-interaction-default />
<aol-control-defaults />
<aol-view [zoom]="7"><aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" /></aol-view>
<aol-layer-vectorimage background="#1a2b39" [imageRatio]="2" [style]="style">
<aol-source-geojson url="assets/poland/voivodeships.geojson" featureProjection="EPSG:3857" />
</aol-layer-vectorimage>
<aol-layer-vector>
<aol-style><aol-style-stroke color="rgba(255, 255, 255, 0.7)" [width]="2" /></aol-style>
<aol-source-vector />
</aol-layer-vector>
</aol-map>
<div class="example-controls">
<span>
Voivodeship <output>{{ name() || '–' }}</output>
</span>
</div>
`,
})
export class ImageVectorLayer {
readonly name = signal('');
protected readonly style = (feature: FeatureLike) =>
new Style({ fill: new Fill({ color: PALETTE[Number(feature.get('code')) / 2 - 1] ?? '#eeeeee' }) });
private readonly map = viewChild.required(MapComponent);
private readonly overlay = viewChild.required(SourceVectorComponent);
private highlighted: Feature | undefined;
protected move(event: MapBrowserEvent): void {
if (!event.dragging) this.showFeatureInfo(event);
}
protected showFeatureInfo(event: MapBrowserEvent): void {
const feature = this.map().instance.forEachFeatureAtPixel(event.pixel, (hit) => hit) as Feature | undefined;
this.name.set(feature?.get('name') ?? '');
if (feature === this.highlighted) return;
const overlay = this.overlay().instance;
if (this.highlighted) overlay.removeFeature(this.highlighted);
if (feature) overlay.addFeature(feature);
this.highlighted = feature;
}
} 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.
image-vector-layer.react.tsximport { useRef, useState } from 'react';
import type OLFeature from 'ol/Feature';
import type { FeatureLike } from 'ol/Feature';
import type OLMap from 'ol/Map';
import type MapBrowserEvent from 'ol/MapBrowserEvent';
import type OLVectorSource from 'ol/source/Vector';
import Fill from 'ol/style/Fill';
import OLStyle from 'ol/style/Style';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
GeoJSONSource,
Map,
Stroke,
Style,
VectorImageLayer,
VectorLayer,
VectorSource,
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 style = (feature: FeatureLike) =>
new OLStyle({ fill: new Fill({ color: PALETTE[Number(feature.get('code')) / 2 - 1] ?? '#eeeeee' }) });
/** The voivodeships rendered as one image by a vector image layer; the one under the pointer is outlined and named. */
export function ImageVectorLayer() {
const [name, setName] = useState('');
const map = useRef<OLMap>(null);
const overlay = useRef<OLVectorSource>(null);
const highlighted = useRef<OLFeature | undefined>(undefined);
const move = (event: MapBrowserEvent): void => {
if (!event.dragging) showFeatureInfo(event);
};
const showFeatureInfo = (event: MapBrowserEvent): void => {
const feature = map.current?.forEachFeatureAtPixel(event.pixel, (hit) => hit) as OLFeature | undefined;
setName(feature?.get('name') ?? '');
if (feature === highlighted.current) return;
const source = overlay.current;
if (highlighted.current) source?.removeFeature(highlighted.current);
if (feature) source?.addFeature(feature);
highlighted.current = feature;
};
return (
<>
<Map ref={map} height="480px" onPointerMove={move} onClick={showFeatureInfo}>
<DefaultInteractions />
<DefaultControls />
<View zoom={7}>
<Coordinate x={19.9368} y={50.0614} srid="EPSG:4326" />
</View>
<VectorImageLayer background="#1a2b39" imageRatio={2} style={style}>
<GeoJSONSource url="assets/poland/voivodeships.geojson" featureProjection="EPSG:3857" />
</VectorImageLayer>
<VectorLayer>
<Style>
<Stroke color="rgba(255, 255, 255, 0.7)" width={2} />
</Style>
<VectorSource ref={overlay} />
</VectorLayer>
</Map>
<div className="example-controls">
<span>
Voivodeship <output>{name || '–'}</output>
</span>
</div>
</>
);
}How the React version works
A VectorImageLayer renders the voivodeships as one image twice the size of the map. The voivodeship under the cursor gets an outline on an ordinary vector layer, and its name appears below the map.
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 and the style function are those of tooltip-on-hover.
From Angular to React
| Angular | React |
|---|---|
<aol-layer-vectorimage [imageRatio]="2"> | <VectorImageLayer imageRatio={2}> |
(pointerMove), (olClick) | onPointerMove, onClick |
| a class field with the highlighted feature | useRef, because it does not affect the React view |
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-layer-vectorimage rasterises its GeoJSON source into a single off-screen canvas over the configured background colour, then translates and scales that cached bitmap cheaply while the camera pans, zooms or animates—re-rendering sharp vector edges only when movement stops. Setting [imageRatio] to 2 sizes that off-screen canvas at twice the viewport width and height so drags up to half a screen wide never expose unrendered blank margins.
For interactive feedback without invalidating the heavy base image on every pixel move, forEachFeatureAtPixel queries the underlying vector geometries and adds the hovered feature itself to a lightweight second vector layer drawn in white.
How it works
aol-layer-vectorimagecaches styled GeoJSON polygons as a single bitmap overbackgroundand transforms that bitmap cheaply during pans and zooms.- Setting
[imageRatio]to2renders a 2× wider and taller off-screen buffer so moderate drags show zero blank edges before the next settled redraw. - A categorical style function assigns each voivodeship one of 16 palette colours from its official two-digit TERYT code (02–32).
- forEachFeatureAtPixel detects the voivodeship under the pointer while a lightweight overlay vector layer draws its white highlight border.
(pointerMove)skips hit detection mid-drag for smoothness, while(olClick)supports tap selection on hoverless touch screens.
Pitfalls
- During active zoom or pan gestures the cached bitmap stretches on screen, causing boundary strokes to thicken or soften briefly until the gesture settles and triggers a fresh vector rasterisation.
- Increasing
[imageRatio]scales off-screen pixel count quadratically—a ratio of2renders four times the viewport area—so avoid values above2on high-DPI mobile screens.
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.