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.

The OpenTopoMap basemap of central Kraków with the Streets, Topography, Humanitarian and Imagery buttons below it, Topography pressed.
A screenshot of the example. Map style © OpenTopoMap (CC-BY-SA). Map data © OpenStreetMap contributors. Elevation: SRTM.

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.ts
import { 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]);
}

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 existing aol-source-xyz via 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-webgltile renders tiles on the GPU, using crossOrigin="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-pressed communicates 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.

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.