Essentials · Angular, React and OpenLayers
One tile source for four basemaps
Switch one WebGL XYZ tile source across four OpenLayers basemaps by updating URL and attributions live without destroying the tile layer.

What this example shows
Over central Kraków, four toggle buttons below the map—Streets, Topography, Humanitarian and Imagery—switch the active basemap between OpenStreetMap, OpenTopoMap, Humanitarian OSM and Esri World Imagery.
Instead of flashing blank white space during a switch, existing tiles remain visible on the WebGL canvas until replacement tiles from the newly selected provider arrive, while bottom-right data credits update in lockstep.
When you need it
Nearly every GIS viewer offers a basemap switcher, yet naively instantiating four separate layers or tearing down layers on each click wastes WebGL textures, resets layer z-index/opacity bindings, or flashes an empty canvas.
When candidate basemaps share the standard global Web Mercator XYZ grid, mutating URL and attribution bindings on a single persistent source keeps memory footprint low and transitions seamless.
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.
reusable-source.tsimport { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { ATTRIBUTION } from 'ol/source/OSM';
import {
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
MapComponent,
SourceXYZComponent,
ViewComponent,
} from 'cc-openlayers';
import { LayerWebGLTileComponent } from 'cc-openlayers/webgl';
interface Basemap {
name: string;
url: string;
attributions: string[];
}
const BASEMAPS: Basemap[] = [
{ name: 'Streets', url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png', attributions: [ATTRIBUTION] },
{
name: 'Topography',
url: 'https://{a-c}.tile.opentopomap.org/{z}/{x}/{y}.png',
attributions: [
'Map style © <a href="https://opentopomap.org/">OpenTopoMap</a> (<a href="https://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA</a>)',
ATTRIBUTION,
],
},
{
name: 'Humanitarian',
url: 'https://{a-c}.tile.openstreetmap.fr/hot/{z}/{x}/{y}.png',
attributions: [
'Tiles style by <a href="https://www.hotosm.org/">Humanitarian OpenStreetMap Team</a> hosted by <a href="https://openstreetmap.fr/">OpenStreetMap France</a>',
ATTRIBUTION,
],
},
{
name: 'Imagery',
url: 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}',
attributions: ['Tiles © Esri — Source: Esri, Maxar, Earthstar Geographics, and the GIS User Community'],
},
];
/** One tile source reused for four basemaps by changing its URL and the attributions that go with it. */
@Component({
selector: 'app-reusable-source',
imports: [
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerWebGLTileComponent,
MapComponent,
SourceXYZComponent,
ViewComponent,
],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<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-webgltile>
<aol-source-xyz [url]="selected().url" [attributions]="selected().attributions" crossOrigin="anonymous" />
</aol-layer-webgltile>
</aol-map>
<div class="example-controls">
@for (basemap of basemaps; track basemap.name) {
<button type="button" [attr.aria-pressed]="selected() === basemap" (click)="selected.set(basemap)">
{{ basemap.name }}
</button>
}
<p class="example-hint">
The source stays the same: only its URL changes, and the tiles are replaced as the new ones load.
</p>
</div>
`,
})
export class ReusableSource {
protected readonly basemaps = BASEMAPS;
protected readonly selected = signal(BASEMAPS[0]);
} 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.
reusable-source.react.tsximport { useState } from 'react';
import { ATTRIBUTION } from 'ol/source/OSM.js';
import { Coordinate, DefaultControls, DefaultInteractions, Map, View, XYZSource } from 'cc-openlayers/react';
import { WebGLTileLayer } from 'cc-openlayers/react/webgl';
interface Basemap {
name: string;
url: string;
attributions: string[];
}
const BASEMAPS: Basemap[] = [
{ name: 'Streets', url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png', attributions: [ATTRIBUTION] },
{
name: 'Topography',
url: 'https://{a-c}.tile.opentopomap.org/{z}/{x}/{y}.png',
attributions: [
'Map style © <a href="https://opentopomap.org/">OpenTopoMap</a> (<a href="https://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA</a>)',
ATTRIBUTION,
],
},
{
name: 'Humanitarian',
url: 'https://{a-c}.tile.openstreetmap.fr/hot/{z}/{x}/{y}.png',
attributions: [
'Tiles style by <a href="https://www.hotosm.org/">Humanitarian OpenStreetMap Team</a> hosted by <a href="https://openstreetmap.fr/">OpenStreetMap France</a>',
ATTRIBUTION,
],
},
{
name: 'Imagery',
url: 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}',
attributions: ['Tiles © Esri — Source: Esri, Maxar, Earthstar Geographics, and the GIS User Community'],
},
];
/** One tile source reused for four basemaps by changing its URL and the attributions that go with it. */
export function ReusableSource() {
const [selected, setSelected] = useState(BASEMAPS[0]);
return (
<>
<Map height="480px">
<DefaultInteractions />
<DefaultControls />
<View zoom={13}>
<Coordinate x={19.9368} y={50.0614} srid="EPSG:4326" />
</View>
<WebGLTileLayer>
<XYZSource url={selected.url} attributions={selected.attributions} crossOrigin="anonymous" />
</WebGLTileLayer>
</Map>
<div className="example-controls">
{BASEMAPS.map((basemap) => (
<button
key={basemap.name}
type="button"
aria-pressed={selected === basemap}
onClick={() => setSelected(basemap)}
>
{basemap.name}
</button>
))}
<p className="example-hint">
The source stays the same: only its URL changes, and the tiles are replaced as the new ones load.
</p>
</div>
</>
);
}How the React version works
Four buttons switch the base map (streets, topography, humanitarian, imagery). The XYZ source in the WebGL layer stays the same: only its URL and attributions change, and the tiles are replaced as they load.
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 list of base maps with their URLs and attributions is the same in both versions.
From Angular to React
| Angular | React |
|---|---|
<aol-layer-webgltile><aol-source-xyz [url]="selected().url"> | <WebGLTileLayer><XYZSource url={selected.url}> |
@for (basemap of basemaps) with (click) | BASEMAPS.map(...) with key and onClick |
[attr.aria-pressed] | aria-pressed |
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. A change of url and attributions calls setUrl and setAttributions on the existing source, so the layer keeps its source object.
Architecture and OpenLayers mechanics
A single aol-layer-webgltile wraps one aol-source-xyz whose [url]="selected().url" and [attributions]="selected().attributions" bindings read from the active basemap signal. Updating the URL rebinds the existing source instance through the wrapper, retaining old tile textures on screen until new tiles finish loading.
Because WebGL uploads raster tiles as GPU textures, crossOrigin="anonymous" is required so browsers permit CORS pixel access, while aria-pressed on the switcher buttons announces the active basemap to assistive technologies.
How it works
[url]="selected().url"updates the existingaol-source-xyzvia OpenLayers’ setUrl without recreating the source or layer.[attributions]="selected().attributions"swaps legal provider credits alongside the tile URL between OpenStreetMap partners and Esri.aol-layer-webgltilerenders tiles on the GPU, usingcrossOrigin="anonymous"so cross-origin tile images can load as WebGL textures.- Previously rendered tiles stay on screen until replacement tiles arrive, preventing blank flashes during basemap changes.
aria-pressedcommunicates the currently active basemap button to screen readers.
Pitfalls
- While new tiles stream in over a slow connection, tiles from the previous and new basemaps briefly appear side by side; that softens street-to-topography switches nicely, but use separate layers if mixing two historical imagery dates mid-load would confuse analysts.
- Never change a tile template URL without updating
[attributions]="selected().attributions"at the same time—each provider enforces distinct licensing credits.
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.