Introduction to Leaflet

This document provides a comprehensive introduction to the Leaflet library, covering its purpose, architectural principles, core components, and the major modernization introduced in version 2.0. This page focuses on the overall system design and entry points to help developers understand how Leaflet is organized and how to work with it effectively.

For detailed information about specific components, see the Core Architecture, Layer System, User Interaction, or Plugin System pages.

What is Leaflet

Leaflet is a leading open-source JavaScript library for building interactive web maps. Weighing approximately 42 KB of gzipped JavaScript plus 4 KB of CSS, it provides a complete mapping solution focused on simplicity, performance, and usability. The library works efficiently across all major desktop and mobile platforms while maintaining a clean, well-documented API.

Leaflet follows a modular architecture where the central Map class coordinates multiple specialized subsystems including layers, controls, event handling, and rendering. The library is designed to handle the essential mapping functionality that most developers need while remaining extensible through a rich plugin ecosystem.

Main Entry Point and Module Structure

100%

Core System Overview

Architectural Principles

Leaflet is built around several key architectural principles that guide its design and implementation:

Modular ESM Design

Starting with version 2.0, Leaflet has transitioned to a fully modular ES Module (ESM) architecture. Instead of a monolithic global L object, the library now exports individual classes and utilities that can be imported as needed:

// Modern ESM approach (v2.0+)
import {Map, TileLayer, Marker} from 'leaflet';

// Legacy approach (v1.x)
const map = L.map('mapId');

Class-Based Architecture

The library uses ES6 classes with a hierarchical inheritance structure. The base Class provides common functionality like options handling and initialization hooks, while specialized classes like Layer, Control, and Handler extend this foundation.

Core Class Hierarchy

100%

Event-Driven Communication

The Evented base class provides a consistent event system throughout the library. Events flow from low-level DOM interactions through layers and controls to the map instance, enabling loose coupling between components.

Core Components

Leaflet's functionality is organized into several major subsystems, each handling specific aspects of mapping:

Map Component

The Map class serves as the central coordinator, managing the view state, coordinate transformations, and orchestrating interactions between layers, controls, and handlers.

Layer System

Layers represent different types of map content including:

• TileLayer: Raster tile-based layers (e.g., OpenStreetMap)
• Marker: Point-based overlays with icons
• Vector Layers: Geometric shapes like polylines and polygons
• LayerGroup: Collections of layers managed as units

Controls and Interaction

User interface components like zoom controls, layer switchers, and attribution, plus event handlers for dragging, zooming, and keyboard navigation.

Rendering Pipeline

Separate Canvas and SVG renderers for vector graphics, with the map automatically selecting the appropriate renderer based on browser capabilities and performance requirements.

Component Relationships

100%

Version 2.0 Modernization

Leaflet 2.0 represents a major modernization effort that brings the library in line with modern JavaScript practices while maintaining its core design philosophy:

Breaking Changes

Area	Change	Impact
Module System	UMD → ESM only	Import statements required, no global L
Class System	Custom classes → ES6 classes	Modern syntax, better tooling support
Events	Mouse/Touch → Pointer Events	Unified input handling
Factory Methods	L.marker() → new Marker()	Direct constructor calls
Browser Support	IE support dropped	Modern evergreen browsers only

Migration Path

The transition from v1.x to v2.0 requires updating code patterns:

// v1.x Pattern
<script src="leaflet.js"></script>
<script>
  const map = L.map('map').setView([51.505, -0.09], 13);
  const tiles = L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png')
    .addTo(map);
</script>

// v2.0 Pattern  
<script type="module">
  import {Map, TileLayer} from 'leaflet';
  
  const map = new Map('map').setView([51.505, -0.09], 13);
  const tiles = new TileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png')
    .addTo(map);
</script>

Legacy Compatibility

For applications requiring backward compatibility, Leaflet provides leaflet-global.js which restores the global L object, and community polyfills are available to ease migration.

Getting Started with Leaflet

Installation Options

Leaflet can be integrated into projects through multiple approaches:

Package Manager (Recommended)

npm install leaflet

CDN with Import Maps

<script type="importmap">
{
  "imports": {
    "leaflet": "https://cdn.jsdelivr.net/npm/leaflet@2.0.0-alpha.1/dist/leaflet.js"
  }
}
</script>

Direct Download Distribution files include leaflet.js (minified), leaflet-src.js (readable), leaflet.css, and associated source maps.

Basic Usage Pattern

Every Leaflet application follows a similar initialization pattern:

1. Create Map Instance: Initialize the map with a container and options
2. Add Base Layer: Typically a tile layer for the map background
3. Add Content: Markers, overlays, and other interactive elements
4. Configure Interaction: Event handlers and controls as needed

File Structure Overview

The Leaflet source code is organized into logical directories that correspond to the major system components:

Source Directory Structure

100%

Directory	Purpose	Key Files
core/	Base classes and utilities	Class.js, Events.js, Browser.js
layer/	All layer types and rendering	Layer.js, tile/TileLayer.js
map/	Core map functionality	Map.js
control/	UI controls and widgets	Control.js, Control.Zoom.js
dom/	DOM utilities and event handling	DomEvent.js, DomUtil.js
geometry/	Geometric data structures	Point.js, Bounds.js
geo/	Geographic coordinate systems	LatLng.js, CRS.js

This modular organization enables developers to understand the codebase systematically and contributes to Leaflet's maintainability and extensibility.