Layers · Angular, React and OpenLayers

Switch layers by zoom level

Switch automatically between OpenStreetMap and aerial orthophotography at zoom 14 using exclusive minZoom and inclusive maxZoom on tile layers.

The orthophotomap of the Main Square and the Old Town of Kraków at zoom 15, above the zoom at which the street map is shown.
A screenshot of the example. Orthophotomap © GUGiK.

What this example shows

Starting at zoom 15 directly over Kraków’s Main Square and Old Town, the map displays sharp national aerial orthophotography. Zooming out just one step to zoom 14 or below automatically swaps the backdrop to OpenStreetMap street cartography—and zooming back past 14 restores the aerial view immediately without any manual basemap toggle.

When you need it

Multi-scale geoportals routinely present generalised vector/street cartography at country and city scales, then transition automatically to detailed aerial orthophotography once the user zooms down to individual parcels and buildings.

Declaring zoom thresholds directly on the layers lets OpenLayers switch backdrops declaratively during smooth animations without writing custom moveend view listeners.

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.

layer-zoom-limits.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { getTopLeft, getWidth } from 'ol/extent';
import { EXTENT } from 'ol/proj/epsg3857';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerTileComponent,
  MapComponent,
  SourceOsmComponent,
  SourceTileWMTSComponent,
  TileGridWMTSComponent,
  ViewComponent,
} from 'cc-openlayers';

const size = getWidth(EXTENT) / 256;

/** The street map at zoom levels 14 and below and the orthophoto of Kraków above them. */
@Component({
  selector: 'app-layer-zoom-limits',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerTileComponent,
    MapComponent,
    SourceOsmComponent,
    SourceTileWMTSComponent,
    TileGridWMTSComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-view [zoom]="15" [maxZoom]="18">
        <aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" />
      </aol-view>
      <!-- visible at zoom levels 14 and below -->
      <aol-layer-tile [maxZoom]="14"><aol-source-osm /></aol-layer-tile>
      <!-- visible at zoom levels above 14 -->
      <aol-layer-tile [minZoom]="14">
        <aol-source-tilewmts
          attributions='Tiles © <a href="https://www.geoportal.gov.pl/" target="_blank">GUGiK</a>'
          crossOrigin="anonymous"
          url="https://mapy.geoportal.gov.pl/wss/service/PZGIK/ORTO/WMTS/StandardResolution"
          layer="ORTOFOTOMAPA"
          matrixSet="EPSG:3857"
          format="image/jpeg"
          projection="EPSG:3857"
          [style]="'default'"
        >
          <aol-tilegrid-wmts [origin]="origin" [resolutions]="resolutions" [matrixIds]="matrixIds" />
        </aol-source-tilewmts>
      </aol-layer-tile>
    </aol-map>
  `,
})
export class LayerZoomLimits {
  protected readonly origin = getTopLeft(EXTENT);
  protected readonly resolutions = Array.from({ length: 20 }, (_, z) => size / 2 ** z);
  protected readonly matrixIds = Array.from({ length: 20 }, (_, z) => `EPSG:3857:${z}`);
}

Architecture and OpenLayers mechanics

OpenLayers evaluates layer zoom ranges on every animation frame—including fractional zoom values mid-pinch or mid-wheel—using half-open interval math: minZoom is exclusive (zoom > minZoom) while maxZoom is inclusive (zoom <= maxZoom).

Giving the street layer [maxZoom] of 14 and the orthophoto layer [minZoom] of 14 partitions the scale continuum cleanly with zero gap and zero double-rendering: up to 14.00 only OpenStreetMap renders and requests tiles, and at 14.01+ only the orthophotomap renders and requests tiles.

How it works

  • Setting [maxZoom] to 14 on OpenStreetMap and [minZoom] to 14 on the orthophotomap ensures exactly one backdrop is active at every scale.
  • OpenLayers checks layer zoom bounds against live fractional view zoom on every render frame, swapping layers seamlessly mid-animation as zoom crosses 14.
  • Layers outside their active [minZoom] / [maxZoom] window neither paint to the canvas nor issue network tile requests.
  • Starting the camera at zoom 15 shows aerial imagery first so zooming out one notch demonstrates the automatic switch immediately.

Pitfalls

  • With an exact hand-off at 14, the street map disappears the instant zoom exceeds 14—leaving the canvas briefly blank on slow connections until the first orthophoto tiles arrive; raising the lower layer’s maxZoom slightly (or keeping it visible underneath) provides a fallback backdrop during loading.
  • Remember the asymmetry: minZoom is exclusive whereas maxZoom is inclusive, so assigning identical threshold numbers (14 and 14) leaves no dead zone between layers.

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.