Tile and image services · Angular, React and OpenLayers
Read raster tiles from PMTiles
Stream Stamen raster tiles directly from a serverless single-file PMTiles archive in OpenLayers using HTTP byte-range requests and object URLs.

What this example shows
Stamen Design raster cartography renders seamlessly inside OpenLayers straight from a single static .pmtiles archive file using HTTP Range requests—requiring zero tile database, Node/Python server or unpacked million-file directory tree.
When you need it
Protomaps PMTiles packs an entire multi-zoom raster or vector pyramid into one cloud-storage-friendly archive addressable via standard HTTP 206 Partial Content byte ranges on S3, R2, Nginx or static hosting.
Integrating pmtiles with OpenLayers lets teams deploy self-contained offline or CDN-cached tile pyramids as a single file.
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.
pmtiles-image.html<aol-map height="480px"
><aol-interaction-default /><aol-control-defaults /><aol-view [zoom]="4"
><aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" /></aol-view
><aol-layer-tile><aol-source-osm /></aol-layer-tile
><aol-layer-webgltile
><aol-source-datatile
[loader]="loader"
[maxZoom]="3"
[transition]="0"
[attributions]="credit" /></aol-layer-webgltile
></aol-map>
<p class="example-hint">This archive ends at zoom 3; closer views enlarge its existing tiles.</p>pmtiles-image.shared.tsimport { PMTiles } from 'pmtiles';
import type { Loader } from 'ol/source/DataTile.js';
export const IMAGE_ARCHIVE = 'https://pmtiles.io/stamen_toner(raster)CC-BY+ODbL_z3.pmtiles';
export const IMAGE_CREDIT = 'Map tiles © Stamen Design, CC BY 4.0; data © OpenStreetMap contributors, ODbL.';
/** Temporary URLs live only until the browser decodes each archive entry. */
export async function decodeArchiveTile(data: Uint8Array): Promise<HTMLImageElement> {
const url = URL.createObjectURL(new Blob([new Uint8Array(data)]));
try {
return await new Promise<HTMLImageElement>((resolve, reject) => {
const image = new Image();
image.onload = () => resolve(image);
image.onerror = () => reject(new Error('Tile image could not be decoded'));
image.src = url;
});
} finally {
URL.revokeObjectURL(url);
}
}
export function archiveLoader(url: string): Loader {
const archive = new PMTiles(url);
return async (z, x, y, options) => {
const tile = await archive.getZxy(z, x, y, options.signal);
if (!tile) throw new Error('Tile is absent from the archive');
return decodeArchiveTile(new Uint8Array(tile.data));
};
}pmtiles-image.tsimport { ChangeDetectionStrategy, Component } from '@angular/core';
import {
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerTileComponent,
MapComponent,
SourceDataTileComponent,
SourceOsmComponent,
ViewComponent,
} from 'cc-openlayers';
import { LayerWebGLTileComponent } from 'cc-openlayers/webgl';
import { archiveLoader, IMAGE_ARCHIVE, IMAGE_CREDIT } from './pmtiles-image.shared';
@Component({
selector: 'app-pmtiles-image',
imports: [
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerTileComponent,
MapComponent,
SourceDataTileComponent,
SourceOsmComponent,
ViewComponent,
LayerWebGLTileComponent,
],
templateUrl: './pmtiles-image.html',
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class PmtilesImage {
protected readonly loader = archiveLoader(IMAGE_ARCHIVE);
protected readonly credit = IMAGE_CREDIT;
} 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.
pmtiles-image.react.tsximport { useMemo } from 'react';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
Map,
View,
TileLayer,
OSMSource,
DataTileSource,
} from 'cc-openlayers/react';
import { WebGLTileLayer } from 'cc-openlayers/react/webgl';
import { archiveLoader, IMAGE_ARCHIVE, IMAGE_CREDIT } from './pmtiles-image.shared';
export function PmtilesImage() {
const loader = useMemo(() => archiveLoader(IMAGE_ARCHIVE), []);
return (
<>
<Map height="480px">
<DefaultInteractions />
<DefaultControls />
<View zoom={4}>
<Coordinate x={19.9368} y={50.0614} srid="EPSG:4326" />
</View>
<TileLayer>
<OSMSource />
</TileLayer>
<WebGLTileLayer>
<DataTileSource loader={loader} maxZoom={3} transition={0} attributions={IMAGE_CREDIT} />
</WebGLTileLayer>
</Map>
<p className="example-hint">This archive ends at zoom 3; closer views enlarge its existing tiles.</p>
</>
);
}pmtiles-image.shared.tsimport { PMTiles } from 'pmtiles';
import type { Loader } from 'ol/source/DataTile.js';
export const IMAGE_ARCHIVE = 'https://pmtiles.io/stamen_toner(raster)CC-BY+ODbL_z3.pmtiles';
export const IMAGE_CREDIT = 'Map tiles © Stamen Design, CC BY 4.0; data © OpenStreetMap contributors, ODbL.';
/** Temporary URLs live only until the browser decodes each archive entry. */
export async function decodeArchiveTile(data: Uint8Array): Promise<HTMLImageElement> {
const url = URL.createObjectURL(new Blob([new Uint8Array(data)]));
try {
return await new Promise<HTMLImageElement>((resolve, reject) => {
const image = new Image();
image.onload = () => resolve(image);
image.onerror = () => reject(new Error('Tile image could not be decoded'));
image.src = url;
});
} finally {
URL.revokeObjectURL(url);
}
}
export function archiveLoader(url: string): Loader {
const archive = new PMTiles(url);
return async (z, x, y, options) => {
const tile = await archive.getZxy(z, x, y, options.signal);
if (!tile) throw new Error('Tile is absent from the archive');
return decodeArchiveTile(new Uint8Array(tile.data));
};
}How the React version works
Read Stamen raster tiles directly from a PMTiles archive using HTTP range requests.
What both versions share
pmtiles locates the requested entry; a temporary object URL decodes its image and is then released.
From Angular to React
| Angular | React |
|---|---|
| A component field holds the archive loader. | useMemo creates one archive loader for the mounted example. |
| An external Angular template declares the example. | JSX declares the example and its controls. |
| The Angular lifecycle releases the mounted resources. | Effect or subscription cleanup releases the mounted resources. |
Who creates, updates and disposes
Both versions share the range reader and image decoder. Temporary URLs are revoked after both successful and failed decoding.
Architecture and OpenLayers mechanics
A shared pmtiles archive reader resolves each requested (z, x, y) tile via Hilbert-curve directory lookups and byte-range fetches, wraps the compressed image bytes in a temporary Blob object URL to decode the bitmap, and immediately revokes the object URL once decoded so browser memory stays flat.
How it works
- The pmtiles reader fetches requested tile byte ranges on demand, decoding each image through a temporary object URL that is revoked immediately after load.
Pitfalls
- This compact demonstration archive contains overview zoom levels
0through3only—zooming in past level 3 smoothly enlarges level-3 tiles rather than loading street-level detail.
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.