Essentials · Angular, React and OpenLayers

A view kept within Poland

Lock an OpenLayers map view inside Poland’s bounding box with the view extent constraint, a ZoomSlider control and document-wide keyboard navigation.

A street map of southern Poland centred on Kraków at zoom 8, with a zoom slider below the zoom buttons.
A screenshot of the example. Map data © OpenStreetMap contributors.

What this example shows

Centred on Kraków at zoom 8, the street map is fenced inside the geographic bounding box of Poland. Dragging toward any border stops cleanly at the national envelope, zooming out halts once Poland fills the frame, a vertical zoom slider beneath the +/− buttons shows the permitted scale span, and arrow or +/− keys navigate the map from anywhere on the page.

When you need it

National geoportals, municipal cadastral viewers, transit networks and regional tourism maps serve data for a bounded territory and gain clarity by keeping users inside that coverage area.

Constraining the view extent prevents accidental pans into blank ocean or unmapped neighbouring regions while automatically establishing a sensible zoom-out floor tailored to the region’s dimensions.

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.

extent-constrained.ts
import { DOCUMENT } from '@angular/common';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import type { Extent } from 'ol/extent';
import {
  ControlZoomSliderComponent,
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerTileComponent,
  MapComponent,
  SourceOsmComponent,
  ViewComponent,
} from 'cc-openlayers';

/** A view constrained to an extent around Poland, with a zoom slider and keyboard navigation from anywhere on the page. */
@Component({
  selector: 'app-extent-constrained',
  imports: [
    ControlZoomSliderComponent,
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerTileComponent,
    MapComponent,
    SourceOsmComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px" [keyboardEventTarget]="document">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-control-zoomslider />
      <aol-view [zoom]="8" [extent]="extent">
        <aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" />
      </aol-view>
      <aol-layer-tile><aol-source-osm /></aol-layer-tile>
    </aol-map>
  `,
})
export class ExtentConstrained {
  protected readonly document = inject(DOCUMENT);
  /** Poland's bounding box in Web Mercator metres. */
  protected readonly extent: Extent = [1558000, 6257000, 2694000, 7362000];
}

Architecture and OpenLayers mechanics

Binding [extent]="extent" ([minX, minY, maxX, maxY]) on the view restricts the entire visible viewport box—not just the centre coordinate—to stay inside Poland’s Web Mercator bounds (1,558,000–2,694,000 E and 6,257,000–7,362,000 N).

Pairing the constrained view with aol-control-zoomslider visualises the exact zoom range left available by that bounding box, while [keyboardEventTarget]="document" routes keyboard arrow pans and +/− zooms globally without requiring focus on the map element first.

How it works

  • [extent]="extent" fences the visible viewport inside Poland’s bounding box, limiting both outward panning and maximum zoom-out.
  • Bounds are specified in projected Web Mercator metres (1,558,000 to 2,694,000 east, 6,257,000 to 7,362,000 north) matching the view projection.
  • aol-control-zoomslider renders a draggable vertical thumb calibrated to the effective zoom range permitted by the extent.
  • [keyboardEventTarget]="document" lets arrow keys and +/− keys pan and zoom from anywhere in the document.

Pitfalls

  • Passing degree coordinates ([14.1, 49.0, 24.2, 54.9]) directly into a Web Mercator view traps the camera inside a roughly 10-metre-wide box near 0°, 0°—always project geographic bounds into metres first.
  • Using document as the keyboard event target overrides normal arrow-key page scrolling; reserve it for full-screen map apps rather than long scrolling articles.
  • Because full-viewport extent clamping also caps zoom-out, use OpenLayers’ center-only constraint option when narrow mobile screens still need wider zoom-out freedom.

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.