Navigation Interactions

Navigation interactions provide the core map navigation capabilities in OpenLayers, enabling users to pan, zoom, and rotate the map through mouse, touch, and keyboard inputs. These interactions modify the View state (center, zoom, rotation) based on user gestures and are subject to view constraints.

For information about the underlying event processing system and condition functions, see Event Processing and Conditions. For feature creation and editing interactions, see Feature Editing Interactions.

Core Navigation Interaction Classes

The navigation interaction system is built around several specialized interaction classes that handle different types of user input:

Mouse-Based Interactions

MouseWheelZoom Interaction

• Primary Class: MouseWheelZoom src/ol/interaction/MouseWheelZoom.js49
• Purpose: Handles mouse wheel scrolling for zoom operations
• Key Features: Supports both trackpad (smooth) and wheel (discrete) modes, configurable anchor point, delta accumulation with timeout

DragPan Interaction

• Primary Class: DragPan src/ol/interaction/DragPan.js35
• Purpose: Enables map panning by dragging with mouse or touch
• Key Features: Kinetic scrolling support, multi-pointer centroid calculation, coordinate transformation

DragRotate Interaction

• Primary Class: DragRotate src/ol/interaction/DragRotate.js31
• Purpose: Allows map rotation by dragging while holding modifier keys
• Key Features: Mouse-only interaction, configurable condition (default: Alt+Shift), angle calculation from map center

Touch-Based Interactions

PinchZoom Interaction

• Primary Class: PinchZoom src/ol/interaction/PinchZoom.js20
• Purpose: Handles two-finger pinch gestures for zooming
• Key Features: Distance-based scaling, anchor point at gesture centroid, bypasses resolution constraints during interaction

PinchRotate Interaction

• Primary Class: PinchRotate src/ol/interaction/PinchRotate.js23
• Purpose: Enables map rotation using two-finger twist gestures
• Key Features: Angle threshold for activation, rotation constraint checking, anchor point calculation

Combined Interactions

DragRotateAndZoom Interaction

• Primary Class: DragRotateAndZoom src/ol/interaction/DragRotateAndZoom.js27
• Purpose: Combines rotation and zoom operations in single drag gesture
• Key Features: Mouse-only, Shift key activation, simultaneous angle and magnitude calculation

DragZoom Interaction

• Primary Class: DragZoom src/ol/interaction/DragZoom.js32
• Purpose: Allows zoom-to-box functionality by dragging a selection rectangle
• Key Features: Extends DragBox, configurable for zoom-in or zoom-out, animated transitions

Navigation Interaction Architecture

100%

Event Conditions and Activation Control

Navigation interactions use condition functions to determine when they should respond to user input. These conditions check modifier keys, input device types, and interaction context.

Primary Condition Functions

Condition Function	Purpose	Default Used By
noModifierKeys	No modifier keys pressed	DragPan
shiftKeyOnly	Only Shift key pressed	DragZoom, DragRotateAndZoom
altShiftKeysOnly	Alt and Shift keys pressed	DragRotate
mouseOnly	Mouse device input only	DragRotate, DragRotateAndZoom
primaryAction	Primary pointer/left mouse button	DragPan
always	Always active	MouseWheelZoom (default)

Focus Management

Several interactions support onFocusOnly configuration to restrict activation when the map has focus:

// Example: DragPan with focus requirement
this.condition_ = options.onFocusOnly
  ? all(focusWithTabindex, condition)
  : condition;

Condition Combination

Conditions can be combined using logical operators:

• all(condition1, condition2, ...) - All conditions must pass
• Multiple conditions passed to constructor are combined with all() automatically

View State Modification Flow

Navigation interactions modify the View state through a structured flow that respects constraints and supports smooth animations.

100%

Interaction State Management

Begin/End Interaction Pattern Most interactions follow a three-phase lifecycle:

1. Begin: view.beginInteraction() - Sets interaction hint, may cancel existing animations
2. Update: Direct state modification with adjust*Internal() methods during interaction
3. End: view.endInteraction() - Applies final constraints, triggers snap animations

Example from DragPan src/ol/interaction/DragPan.js93-98:

if (!this.panning_) {
  this.panning_ = true;
  map.getView().beginInteraction();
}

Example from PinchZoom src/ol/interaction/PinchZoom.js106-111:

const direction = this.lastScaleDelta_ > 1 ? 1 : -1;
view.endInteraction(this.duration_, direction);

Constraint Bypass During Interaction

During active interaction, many constraints are bypassed to allow smooth manipulation:

• Resolution constraints allow intermediate zoom levels src/ol/resolutionconstraint.js101-110
• Center constraints permit temporary overscroll src/ol/centerconstraint.js57-66
• Rotation constraints are relaxed for smooth rotation

Configuration and Customization

Common Configuration Options

All navigation interactions support standard configuration patterns:

Option	Purpose	Default	Used By
condition	Activation condition function	Varies by interaction	All
duration	Animation duration (ms)	250-400	Most
onFocusOnly	Require map focus	false	Mouse interactions

Interaction-Specific Options

MouseWheelZoom Configuration src/ol/interaction/MouseWheelZoom.js14-30:

{
  maxDelta: 1,           // Maximum zoom delta per wheel event
  duration: 250,         // Animation duration
  timeout: 80,           // Accumulation timeout
  useAnchor: true,       // Zoom to mouse position
  constrainResolution: false  // Force discrete zoom levels
}

DragPan Configuration src/ol/interaction/DragPan.js21-28:

{
  condition: all(noModifierKeys, primaryAction),  // Activation condition
  kinetic: undefined,    // Kinetic scrolling object
  onFocusOnly: false     // Focus requirement
}

Touch Interaction Configuration:

• PinchZoom: duration (400ms default)
• PinchRotate: duration (250ms), threshold (0.3 radians)

Runtime Configuration

Some interactions provide methods for runtime configuration changes:

MouseWheelZoom Anchor Control src/ol/interaction/MouseWheelZoom.js312-317:

interaction.setMouseAnchor(false);  // Disable anchor-based zooming

Default Navigation Setup

OpenLayers provides a default set of navigation interactions through the defaults() function. While the specific implementation isn't shown in the provided files, the test files indicate the standard combination:

Standard Default Interactions

Based on test imports and usage patterns test/browser/spec/ol/Map.test.js16-22:

1. DragPan - Primary navigation method
2. MouseWheelZoom - Desktop zoom control
3. PinchZoom - Touch zoom control
4. PinchRotate - Touch rotation control
5. DoubleClickZoom - Quick zoom functionality

Integration with Map

Navigation interactions are automatically:

• Added to the Map's interaction collection
• Connected to the map's event system via setMap()
• Provided with access to View through map.getView()
• Subject to the map's viewport and coordinate systems

Map Integration Example test/browser/spec/ol/Map.test.js115-124:

const map = new Map({});
const interactions = map.getInteractions();
// Default interactions are automatically added
for (let i = 0; i < interactions.getLength(); ++i) {
  expect(interactions.item(i).getMap()).to.be(map);
}