Essentials · Angular, React and OpenLayers

Two-finger panning in a scrolling page

Enable cooperative mobile two-finger panning and Cmd/Ctrl wheel zoom in OpenLayers so single-finger touch swipes and plain wheel events scroll the page.

A street map of Kraków at zoom 12 with the hint below it: pan with two fingers or hold Cmd/Ctrl and drag.
A screenshot of the example. Map data © OpenStreetMap contributors.

What this example shows

Centred on Kraków at zoom 12 with an explicit usage hint beneath the canvas, this map implements cooperative gesture handling: swiping with one finger on a phone or rolling an unmodified mouse wheel on desktop scrolls the surrounding web page smoothly.

Using two fingers on a touch screen—or holding Cmd on macOS / Ctrl on Windows and Linux while dragging or scrolling—pans and zooms the map itself.

When you need it

On smartphones, a full-width embedded map taller than half the screen becomes an inescapable touch trap if single-finger drags pan the map instead of scrolling the page.

Users conditioned by major consumer mapping embeds expect cooperative gestures: one finger moves the document, two fingers explore the map, and desktop modifier keys protect trackpad scrolling.

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.

two-finger-pan-scroll.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  DragPanInteractionComponent,
  LayerTileComponent,
  MapComponent,
  MouseWheelZoomInteractionComponent,
  SourceOsmComponent,
  ViewComponent,
} from 'cc-openlayers';
import { platformModifierKeyOnly } from 'ol/events/condition';
import type DragPan from 'ol/interaction/DragPan';

/** A map that lets the page scroll: it pans with two fingers or Cmd/Ctrl and zooms with the wheel only while Cmd/Ctrl is held. */
@Component({
  selector: 'app-two-finger-pan-scroll',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    DragPanInteractionComponent,
    LayerTileComponent,
    MapComponent,
    MouseWheelZoomInteractionComponent,
    SourceOsmComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px">
      <aol-interaction-default [dragPan]="false" [mouseWheelZoom]="false" />
      <aol-interaction-dragpan [condition]="panCondition" />
      <aol-interaction-mousewheelzoom [condition]="wheelCondition" />
      <aol-control-defaults />
      <aol-view [zoom]="12"><aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" /></aol-view>
      <aol-layer-tile><aol-source-osm /></aol-layer-tile>
    </aol-map>
    <div class="example-controls">
      <p class="example-hint">Pan with two fingers or hold Cmd/Ctrl and drag; hold Cmd/Ctrl to zoom with the wheel.</p>
    </div>
  `,
})
export class TwoFingerPanScroll {
  protected readonly panCondition = function (
    this: DragPan,
    event: Parameters<typeof platformModifierKeyOnly>[0]
  ): boolean {
    return this.getPointerCount() === 2 || platformModifierKeyOnly(event);
  };
  protected readonly wheelCondition = platformModifierKeyOnly;
}

Architecture and OpenLayers mechanics

The template disables unconditional pan and wheel handlers inside the default interaction bundle via [dragPan]="false" and [mouseWheelZoom]="false", then mounts standalone aol-interaction-dragpan and aol-interaction-mousewheelzoom components configured with custom event conditions.

On the drag-pan interaction, panCondition evaluates this.getPointerCount() === 2 (two-finger touch) or platformModifierKeyOnly (Cmd/Ctrl + mouse drag). Crucially, panCondition is written as a classic function expression rather than an arrow function because OpenLayers invokes DragPan condition callbacks with the DragPan instance bound as this. When the condition returns false, OpenLayers leaves the native touch/wheel event uncancelled so the browser scrolls the page.

How it works

  • [dragPan]="false" and [mouseWheelZoom]="false" exclude unconditional pan and wheel handlers from the defaults while aol-interaction-dragpan and aol-interaction-mousewheelzoom re-add them with modifier rules.
  • panCondition activates panning only when this.getPointerCount() === 2 or platformModifierKeyOnly (Cmd on macOS, Ctrl elsewhere) is true.
  • Declaring panCondition as a regular function preserves OpenLayers’ dynamic this binding on the DragPan interaction instance.
  • Because OpenLayers only cancels browser touch-scroll when an interaction claims the gesture, rejected single-finger swipes scroll the page naturally.

Pitfalls

  • Writing panCondition as an arrow function lexically binds this to the outer Angular component or undefined, causing getPointerCount to throw at runtime.
  • Always display clear user guidance (or a transient overlay banner) explaining two-finger / Cmd+Ctrl gestures so visitors do not think the map is frozen.
  • Check CSS touch-action overrides on parent containers so custom stylesheets do not block native vertical page scrolling over the viewport.

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.