Tile and image services · Angular, React and OpenLayers
A watercolour map with labels over it
Stack transparent Esri reference labels and borders above archival Stamen Watercolor tiles in OpenLayers while capping source maxZoom at 18.

What this example shows
Central Kraków at zoom 12 appears painted in warm hand-crafted washes—ochre streets and emerald parkland from Stamen Design’s iconic Watercolor tiles preserved by the Smithsonian’s Cooper Hewitt museum—made practical for navigation by a crisp upper layer of Esri place names and administrative boundaries.
When you need it
Editorial storytelling maps, tourism guides, museum exhibits and satellite viewers frequently pair unlabelled artistic or photographic base imagery with a dedicated transparent reference-label overlay.
Separating background washes or imagery from foreground typography also lets you insert thematic polygons in between—painting flood zones or districts over the artwork while keeping city names crisp and unobstructed on top.
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.
stamen.tsimport { ChangeDetectionStrategy, Component } from '@angular/core';
import { ATTRIBUTION } from 'ol/source/OSM';
import {
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerTileComponent,
MapComponent,
SourceXYZComponent,
ViewComponent,
} from 'cc-openlayers';
/**
* Two tile layers composed: Stamen's watercolor map of Kraków, as the Cooper Hewitt, Smithsonian Design Museum keeps
* it, with Esri's place names and borders drawn over it.
*/
@Component({
selector: 'app-stamen',
imports: [
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerTileComponent,
MapComponent,
SourceXYZComponent,
ViewComponent,
],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<aol-map height="480px">
<aol-interaction-default />
<aol-control-defaults />
<aol-view [zoom]="12">
<aol-coordinate [x]="19.9373" [y]="50.0617" srid="EPSG:4326" />
</aol-view>
<aol-layer-tile>
<aol-source-xyz
url="https://watercolormaps.collection.cooperhewitt.org/tile/watercolor/{z}/{x}/{y}.jpg"
[minZoom]="1"
[maxZoom]="18"
[attributions]="watercolor"
/>
</aol-layer-tile>
<aol-layer-tile>
<aol-source-xyz
url="https://server.arcgisonline.com/ArcGIS/rest/services/Reference/World_Boundaries_and_Places/MapServer/tile/{z}/{y}/{x}"
attributions="Labels © Esri — Esri, HERE, Garmin, © OpenStreetMap contributors, and the GIS user community"
/>
</aol-layer-tile>
</aol-map>
`,
})
export class Stamen {
protected readonly watercolor = [
'Map tiles by <a href="https://stamen.com/">Stamen Design</a>, under ' +
'<a href="https://creativecommons.org/licenses/by/3.0">CC BY 3.0</a>, from the ' +
'<a href="https://watercolormaps.collection.cooperhewitt.org/">Cooper Hewitt archive</a>',
ATTRIBUTION,
];
} 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.
stamen.react.tsximport { ATTRIBUTION } from 'ol/source/OSM.js';
import { Coordinate, DefaultControls, DefaultInteractions, Map, TileLayer, View, XYZSource } from 'cc-openlayers/react';
const WATERCOLOR = [
'Map tiles by <a href="https://stamen.com/">Stamen Design</a>, under ' +
'<a href="https://creativecommons.org/licenses/by/3.0">CC BY 3.0</a>, from the ' +
'<a href="https://watercolormaps.collection.cooperhewitt.org/">Cooper Hewitt archive</a>',
ATTRIBUTION,
];
/**
* Two tile layers composed: Stamen's watercolor map of Kraków, as the Cooper Hewitt, Smithsonian Design Museum keeps
* it, with Esri's place names and borders drawn over it.
*/
export function Stamen() {
return (
<Map height="480px">
<DefaultInteractions />
<DefaultControls />
<View zoom={12}>
<Coordinate x={19.9373} y={50.0617} srid="EPSG:4326" />
</View>
<TileLayer>
<XYZSource
url="https://watercolormaps.collection.cooperhewitt.org/tile/watercolor/{z}/{x}/{y}.jpg"
minZoom={1}
maxZoom={18}
attributions={WATERCOLOR}
/>
</TileLayer>
<TileLayer>
<XYZSource
url="https://server.arcgisonline.com/ArcGIS/rest/services/Reference/World_Boundaries_and_Places/MapServer/tile/{z}/{y}/{x}"
attributions="Labels © Esri — Esri, HERE, Garmin, © OpenStreetMap contributors, and the GIS user community"
/>
</TileLayer>
</Map>
);
}How the React version works
Stamen's watercolour tiles from the Cooper Hewitt archive with place labels on top; the archive holds only levels 1–18.
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 |
|---|---|
<aol-source-xyz [minZoom] [maxZoom]> | <XYZSource minZoom maxZoom> |
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
Two aol-layer-tile elements stack in template order: the bottom aol-source-xyz fetches Stamen Watercolor tiles from the Smithsonian archive with [maxZoom] capped at 18 (the deepest level in the archive), while the top aol-source-xyz fetches Esri’s transparent World Boundaries and Places PNGs using {z}/{y}/{x} row-first coordinates.
Because [maxZoom] is declared on the watercolour source, zooming in to level 19 or 20 smoothly upscales level-18 tiles instead of requesting non-existent files.
How it works
- The bottom
aol-source-xyzloads unlabelled Stamen Watercolor tiles preserved in the Cooper Hewitt museum collection. - The upper
aol-source-xyzoverlays transparent Esri World Boundaries and Places labels using ArcGIS row-before-column URL order. - Setting source
[maxZoom]to18lets OpenLayers overzoom level-18 watercolour tiles cleanly when users zoom closer.
Pitfalls
- Because the museum archive serves watercolour tiles without CORS headers, they display normally in standard 2D canvas layers but taint the canvas—meaning map exports through canvas.toDataURL or pixel readbacks fail on that layer; the archive would also have to send CORS headers before the source could request them.
- Always keep reference label layers at the top of the layer stack (or assign a high Z-index) so thematic fills do not paint over town and street names.
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.