Raster, GeoTIFF and WebGL · Angular, React and OpenLayers
Render map tiles in a worker
Render OpenStreetMap tiles inside a dedicated Web Worker OffscreenCanvas in OpenLayers and transfer ImageBitmaps to keep UI threads responsive.

What this example shows
An interactive OpenStreetMap view of Kraków composites its visible tiles from 512-pixel ImageBitmaps rendered off the main browser thread inside a dedicated module Web Worker—keeping main-thread controls and animations smooth.
When you need it
Complex multi-layer tile composition, dense vector-to-tile styling or CPU-heavy map overlays can cause frame drops on the main UI thread while forms, charts or animations run alongside the map.
Delegating tile rendering to a headless OpenLayers map targeting an OffscreenCanvas inside a Web Worker isolates rendering work from main-thread UI responsiveness.
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.
offscreen-client.tsexport interface OffscreenClient {
loader(z: number, x: number, y: number): Promise<ImageBitmap>;
dispose(): void;
}
interface Job {
id: number;
tile: number[];
resolve(image: ImageBitmap): void;
reject(error: Error): void;
}
interface Reply {
action: 'rendered' | 'error';
id: number;
image?: ImageBitmap;
error?: string;
}
/** One worker map renders one tile at a time; every request settles even if rendering fails. */
export function createOffscreenClient(worker: Worker, onError: () => void, timeout = 20000): OffscreenClient {
const queue: Job[] = [];
let sequence = 0;
let stopped = false;
let timer: ReturnType<typeof setTimeout> | undefined;
const next = () => {
const job = queue[0];
if (!job || stopped) return;
timer = setTimeout(() => finish(undefined, new Error('Worker render timed out')), timeout);
try {
worker.postMessage({ action: 'render', id: job.id, tile: job.tile });
} catch {
finish(undefined, new Error('Worker could not receive the tile'));
}
};
const finish = (image?: ImageBitmap, error?: Error) => {
clearTimeout(timer);
const job = queue.shift();
if (error) {
job?.reject(error);
onError();
} else if (image) {
job?.resolve(image);
}
next();
};
const message = (event: MessageEvent<Reply>) => {
const { action, id, image, error } = event.data;
if (stopped || queue[0]?.id !== id) {
image?.close();
return;
}
if (action === 'rendered' && image) finish(image);
else if (action === 'error') finish(undefined, new Error(error ?? 'Worker render failed'));
};
const dispose = () => {
if (stopped) return;
stopped = true;
clearTimeout(timer);
worker.terminate();
worker.removeEventListener('error', fault);
worker.removeEventListener('messageerror', fault);
// Keep the message handler to close bitmaps already posted before termination.
for (const job of queue.splice(0)) job.reject(new Error('Worker disposed'));
};
const fault = () => {
onError();
dispose();
};
worker.addEventListener('message', message);
worker.addEventListener('error', fault);
worker.addEventListener('messageerror', fault);
return {
loader: (z, x, y) => {
if (stopped) return Promise.reject(new Error('Worker disposed'));
return new Promise<ImageBitmap>((resolve, reject) => {
queue.push({ id: ++sequence, tile: [z, x, y], resolve, reject });
if (queue.length === 1) next();
});
},
dispose,
};
}
export function supportsOffscreenRendering(): boolean {
return typeof Worker !== 'undefined' && typeof OffscreenCanvas !== 'undefined';
}
export function startOffscreenClient(onError: () => void): OffscreenClient {
return createOffscreenClient(
new Worker(new URL('./tiled-layer-rendering-in-offscreen-canvas.worker', import.meta.url), { type: 'module' }),
onError
);
}tiled-layer-rendering-in-offscreen-canvas.tsimport { afterNextRender, ChangeDetectionStrategy, Component, DestroyRef, inject, signal } from '@angular/core';
import {
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerTileComponent,
MapComponent,
SourceImageTileComponent,
ViewComponent,
} from 'cc-openlayers';
import { type OffscreenClient, startOffscreenClient, supportsOffscreenRendering } from './offscreen-client';
/** Tile images are rendered in a worker's OpenLayers map on an OffscreenCanvas. */
@Component({
selector: 'app-tiled-layer-rendering-in-offscreen-canvas',
imports: [
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerTileComponent,
MapComponent,
SourceImageTileComponent,
ViewComponent,
],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
@if (client(); as renderer) {
<aol-map height="480px">
<aol-interaction-default />
<aol-control-defaults />
<aol-view [zoom]="13">
<aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" />
</aol-view>
<aol-layer-tile>
<aol-source-imagetile [tileSize]="512" [loader]="renderer.loader" [attributions]="attributions" />
</aol-layer-tile>
</aol-map>
} @else {
<p class="example-hint">This example needs Web Workers and OffscreenCanvas.</p>
}
@if (failed()) {
<p class="example-hint" role="status">The worker could not render the map.</p>
}
`,
})
export class TiledLayerRenderingInOffscreenCanvas {
readonly client = signal<OffscreenClient | null>(null);
readonly failed = signal(false);
readonly attributions =
'<a href="https://www.openstreetmap.org/copyright" target="_blank">© OpenStreetMap contributors</a>';
constructor() {
const destroy = inject(DestroyRef);
afterNextRender(() => {
if (!supportsOffscreenRendering()) return;
try {
const client = startOffscreenClient(() => this.failed.set(true));
this.client.set(client);
destroy.onDestroy(() => client.dispose());
} catch {
this.failed.set(true);
}
});
}
}tiled-layer-rendering-in-offscreen-canvas.worker.tsimport Map from 'ol/Map.js';
import View from 'ol/View.js';
import TileLayer from 'ol/layer/Tile.js';
import { unByKey } from 'ol/Observable.js';
import OSM from 'ol/source/OSM.js';
import { createXYZ } from 'ol/tilegrid.js';
import type { TileCoord } from 'ol/tilecoord.js';
const worker = self as unknown as {
addEventListener(
type: 'message',
listener: (event: MessageEvent<{ action: string; id: number; tile: TileCoord }>) => void
): void;
postMessage(
message: { action: string; id: number; error?: string; image?: ImageBitmap },
transfer?: Transferable[]
): void;
};
const tileGrid = createXYZ({ tileSize: 512 });
const canvas = new OffscreenCanvas(512, 512);
const source = new OSM({ transition: 0 });
// OpenLayers supports OffscreenCanvas targets; its DOM declaration retains HTMLElement.
const map = new Map({ target: canvas as unknown as HTMLElement, layers: [new TileLayer({ source })] });
let cleanup: (() => void) | undefined;
worker.addEventListener('message', ({ data }: MessageEvent<{ action: string; id: number; tile: TileCoord }>) => {
if (data.action !== 'render') return;
cleanup?.();
let settled = false;
const timer = setTimeout(() => finish('Render timed out'), 15000);
const clear = () => {
clearTimeout(timer);
if (complete) unByKey(complete);
if (failed) unByKey(failed);
};
const finish = (error?: string) => {
if (settled) return;
settled = true;
clear();
if (error) {
worker.postMessage({ action: 'error', id: data.id, error });
return;
}
try {
const image = canvas.transferToImageBitmap();
worker.postMessage({ action: 'rendered', id: data.id, image }, [image]);
} catch {
worker.postMessage({ action: 'error', id: data.id, error: 'Bitmap transfer failed' });
}
};
cleanup = () => {
settled = true;
clear();
};
const complete = map.once('rendercomplete', () => finish());
const failed = source.on('tileloaderror', () => finish('Tile loading failed'));
try {
map.setView(
new View({ center: tileGrid.getTileCoordCenter(data.tile), resolution: tileGrid.getResolution(data.tile[0]) })
);
} catch {
finish('Render failed');
}
}); 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.
tiled-layer-rendering-in-offscreen-canvas.react.tsximport { useState, useSyncExternalStore } from 'react';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
ImageTileSource,
Map,
TileLayer,
View,
} from 'cc-openlayers/react';
import { type OffscreenClient, startOffscreenClient, supportsOffscreenRendering } from './offscreen-client';
const attributions =
'<a href="https://www.openstreetmap.org/copyright" target="_blank">© OpenStreetMap contributors</a>';
/** Tile images are rendered in a worker's OpenLayers map on an OffscreenCanvas. */
export function TiledLayerRenderingInOffscreenCanvas() {
const [store] = useState(() => {
const empty = { client: null as OffscreenClient | null, failed: false };
let snapshot = empty;
return {
getSnapshot: () => snapshot,
getServerSnapshot: () => empty,
subscribe: (changed: () => void) => {
if (!supportsOffscreenRendering()) return () => undefined;
let client: OffscreenClient | undefined;
const fail = () => {
snapshot = { ...snapshot, failed: true };
changed();
};
try {
client = startOffscreenClient(fail);
snapshot = { client, failed: false };
changed();
} catch {
fail();
}
return () => {
client?.dispose();
snapshot = empty;
};
},
};
});
const { client, failed } = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
return (
<>
{client ? (
<Map height="480px">
<DefaultInteractions />
<DefaultControls />
<View zoom={13}>
<Coordinate x={19.9368} y={50.0614} srid="EPSG:4326" />
</View>
<TileLayer>
<ImageTileSource tileSize={512} loader={client.loader} attributions={attributions} />
</TileLayer>
</Map>
) : (
<p className="example-hint">This example needs Web Workers and OffscreenCanvas.</p>
)}
{failed ? (
<p className="example-hint" role="status">
The worker could not render the map.
</p>
) : null}
</>
);
}How the React version works
Render OpenStreetMap tiles around Kraków in a module worker and transfer image bitmaps to the visible Angular or React map.
What both versions share
Both versions use the same worker client and module worker. The client queues requests and matches replies by id. The worker renders an OpenLayers map on a 512-pixel OffscreenCanvas and transfers the result as an ImageBitmap; the visible ImageTile source receives that bitmap.
From Angular to React
| Angular | React |
|---|---|
| afterNextRender starts the client in the browser | useSyncExternalStore subscribes to the worker resource |
| signal stores client and failure state | the external store exposes client and failure state |
| DestroyRef terminates the worker | unsubscribe terminates the worker |
Who creates, updates and disposes
Only browser lifecycle hooks create a worker. Cleanup terminates it and rejects outstanding requests. Worker faults and render timeouts settle work rather than leaving promises pending; late orphan bitmaps are closed. Unsupported environments show a placeholder instead of attempting server-side worker creation.
Architecture and OpenLayers mechanics
A dedicated module worker instantiates its own headless OpenLayers Map backed by a 512-pixel OffscreenCanvas. On the main thread, the visible image-tile source delegates tile loads through a serialized request client that correlates worker replies by request ID, transfers finished ImageBitmaps back with zero pixel copying, settles pending promises on timeouts or worker errors, and terminates the worker when the component unmounts.
How it works
- A background module worker runs an OpenLayers map instance rendering onto a 512-pixel OffscreenCanvas.
- A serialized client queue matches asynchronous tile requests and transferred ImageBitmap replies by request ID.
- Timeouts, error handlers and component teardown settle in-flight promises and terminate the worker cleanly.
Pitfalls
- Both Web Workers and OffscreenCanvas must be supported by the browser runtime (and workers are skipped during Server-Side Rendering, with an explicit fallback message shown on unsupported environments).
- Because requests serialize through a single worker map instance, this pattern offloads work from the UI thread rather than parallelising across multiple worker threads.
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.