User Interaction

This document covers Leaflet's user interaction system, which handles input from users through mouse, touch, keyboard, and pointer events and translates them into map behaviors like panning, zooming, and element selection. This includes the DOM event processing pipeline, the draggable element system, and the map interaction handlers that provide behaviors like drag-to-pan and scroll-to-zoom.

For information about UI controls like zoom buttons and layer switchers, see Controls. For details about DOM utilities and low-level event processing, see DOM Utilities and Event Handling. For specifics about map interaction behaviors, see Map Interaction Handlers.

Interaction Pipeline Overview

Leaflet's user interaction system processes raw DOM events through multiple layers, transforming basic input into meaningful map interactions. The system is designed to handle modern web input methods including touch, pointer events, and traditional mouse/keyboard input.

100%

Core Interaction Components

The interaction system is built around several key components that work together to provide a smooth user experience across different devices and input methods.

DOM Event Foundation

The DomEvent module provides the foundation for all user interaction by normalizing browser differences and providing a consistent event handling interface. It handles pointer event detection, touch event processing, and cross-browser compatibility.

Component	Purpose	Key Functions
DomEvent.on()	Event listener registration	Supports multiple event types and contexts
DomEvent.getPointerPosition()	Coordinate extraction	Normalizes client coordinates relative to containers
DomEvent.getWheelDelta()	Scroll wheel processing	Handles different wheel event formats
DomEvent.stopPropagation()	Event control	Prevents unwanted event bubbling

Draggable Element System

The Draggable class provides the core dragging functionality used throughout Leaflet for map panning, marker dragging, and other drag interactions. It implements pointer capture, tolerance checking, and drag state management.

100%

Browser Capability Detection

The Browser module detects device and browser capabilities to optimize interaction handling for different environments. This affects how touch events, pointer events, and device-specific behaviors are processed.

Property	Detection Target	Impact on Interaction
Browser.touch	Touch capability	Enables touch gesture processing
Browser.pointer	Pointer Events API	Uses modern pointer event handling
Browser.mobile	Mobile device	Adjusts interaction tolerances
Browser.retina	High-DPI display	Affects pixel calculations

Event Flow Architecture

User interactions flow through a well-defined pipeline that transforms raw DOM events into structured map behaviors. The system uses event delegation and normalization to ensure consistent behavior across platforms.

100%

Input Device Support

Leaflet's interaction system supports multiple input methods simultaneously, with automatic detection and appropriate handling for each device type.

Pointer Event Handling

Modern browsers support the Pointer Events API, which unifies mouse, touch, and pen input. Leaflet detects this capability and uses it when available, falling back to separate mouse and touch event handling for older browsers.

Touch Gesture Processing

Touch interactions include special handling for:

• Single touch: Translated to pointer events for consistent processing
• Multi-touch: Detected and handled for zoom gestures
• Touch tolerance: Larger tolerance values for finger-based interaction
• Pointer capture: Prevents conflicts between simultaneous touches

Mouse and Keyboard Integration

Traditional mouse and keyboard interactions are preserved with full functionality:

• Mouse wheel: Zoom with configurable sensitivity and debouncing
• Keyboard modifiers: Shift+drag for box zoom, modifier keys for zoom direction
• Context menu: Proper integration with browser context menus
• Focus management: Keyboard navigation support where appropriate

Handler System Integration

The interaction system integrates with Leaflet's Handler architecture to provide modular, configurable map behaviors. Each interaction type is implemented as a Handler that can be enabled or disabled independently.

Handler Lifecycle

100%

Core Map Handlers

Handler	Event Triggers	Interaction Result
Map.Drag	pointerdown on map container	Pan with optional inertia
ScrollWheelZoom	wheel events	Zoom toward cursor position
BoxZoom	pointerdown + shiftKey	Zoom to selected rectangle
DoubleClickZoom	dblclick events	Zoom in/out at click point

Each handler manages its own event listeners and interaction state, ensuring clean separation of concerns and the ability to customize behavior per interaction type.