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.

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.tsimport { 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}`);
} 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.
layer-zoom-limits.react.tsximport { getTopLeft, getWidth } from 'ol/extent';
import { EXTENT } from 'ol/proj/epsg3857';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
Map,
OSMSource,
TileLayer,
View,
WMTSSource,
useWMTSTileGrid,
} from 'cc-openlayers/react';
const size = getWidth(EXTENT) / 256;
const origin = getTopLeft(EXTENT);
const resolutions = Array.from({ length: 20 }, (_, z) => size / 2 ** z);
const matrixIds = Array.from({ length: 20 }, (_, z) => `EPSG:3857:${z}`);
/** The street map at zoom levels 14 and below and the orthophoto of Kraków above them. */
export function LayerZoomLimits() {
const tileGrid = useWMTSTileGrid({ origin, resolutions, matrixIds });
return (
<Map height="480px">
<DefaultInteractions />
<DefaultControls />
<View zoom={15} maxZoom={18}>
<Coordinate x={19.9368} y={50.0614} srid="EPSG:4326" />
</View>
{/* visible at zoom levels 14 and below */}
<TileLayer maxZoom={14}>
<OSMSource />
</TileLayer>
{/* visible at zoom levels above 14 */}
<TileLayer minZoom={14}>
<WMTSSource
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"
tileGrid={tileGrid}
/>
</TileLayer>
</Map>
);
}How the React version works
Up to zoom 14 the street map shows, above it Kraków's orthophoto. The layers' maxZoom and minZoom set the limits, without any code.
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. Both versions compute the WMTS tile grid of GUGiK's orthophoto (origin, 20 resolutions, ids EPSG:3857:z) in the same way; in React the useWMTSTileGrid hook creates it once from module constants.
From Angular to React
| Angular | React |
|---|---|
[maxZoom]="14", [minZoom]="14" on aol-layer-tile | maxZoom={14}, minZoom={14} on TileLayer |
| HTML comments in the template | JSX comments {/* … */} |
<aol-source-tilewmts> with <aol-tilegrid-wmts> inside | <WMTSSource tileGrid={tileGrid}> with useWMTSTileGrid(...) |
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
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
maxZoomslightly (or keeping it visible underneath) provides a fallback backdrop during loading. - Remember the asymmetry:
minZoomis exclusive whereasmaxZoomis inclusive, so assigning identical threshold numbers (14and14) leaves no dead zone between layers.
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.