Plugin System

This document explains Leaflet's plugin architecture, how third-party plugins extend the library's functionality, and the plugin discovery and submission mechanisms. Plugins allow developers to add features beyond Leaflet's lightweight core without modifying the library itself.

For information about Leaflet's core extensibility mechanisms (Class inheritance, Evented system, option merging), see Utilities and Class System. For details on extending specific components, see Layer Base Class, Controls, and Map Interaction Handlers.

Purpose and Design Philosophy

Leaflet is designed to be lightweight and focused on core mapping functionality. The plugin system enables the community to extend Leaflet with additional features without bloating the core library. Plugins can add new layer types, controls, interaction handlers, data formats, and integration with external services.

The plugin architecture leverages Leaflet's class-based inheritance system and the global L namespace to provide well-defined extension points. Plugins are distributed as standalone JavaScript modules that users can include alongside the core Leaflet library.

Plugin Extension Points

Plugins extend Leaflet by hooking into one of several architectural extension points. Each extension point corresponds to a base class or system in Leaflet's architecture.

Extension Point Architecture

100%

Common Extension Patterns

Plugins typically follow one of these integration patterns:

Pattern	Base Class	Use Case	Example Plugin Types
Layer Extension	L.Layer, L.TileLayer, L.GridLayer	New data sources or visualization types	Basemap providers, Vector tiles, Heatmaps
Vector Layer Extension	L.Path, L.Polyline, L.Polygon	Custom geometric shapes	Editable geometries, Animated paths
Marker Extension	L.Marker, L.Icon, L.DivIcon	Custom marker types	Marker clusters, Animated markers
Control Extension	L.Control	UI widgets and panels	Layer switchers, Measurement tools, Sidebars
Handler Extension	L.Handler	New interaction modes	Drawing tools, Gesture handlers
Renderer Extension	L.Renderer, L.Canvas, L.SVG	Custom rendering strategies	WebGL renderers, Special effects
Utility Addition	L namespace	Helper functions	Geocoding, Routing, Geoprocessing

Plugin Categories

Leaflet's plugin database organizes plugins into hierarchical categories based on functionality. The categorization system helps users discover relevant plugins for their needs.

Plugin Category Taxonomy

100%

Category Descriptions

Tile & Image Layers

Plugins that provide new basemap sources or modify how tiles and images are loaded and displayed:

• Basemap Providers: Pre-configured tile layers from services like OpenStreetMap, Mapbox, Stamen, etc.
• Basemap Formats: Support for formats like WMS, WMTS, ArcGIS REST
• Non-map Base Layers: Display large custom images (zoomable artwork, floor plans)
• Tile/Image Display: Effects like fading, filtering, or custom tile positioning
• Tile Load: Optimize or modify tile loading behavior
• Vector Tiles: Render Mapbox Vector Tiles (MVT) or other vector tile formats

Overlay Data

Plugins that load vector overlay data (points, lines, polygons) from various sources:

• Overlay Data Formats: Parse KML, GPX, TopoJSON, CSV, and other GIS formats
• Dynamic Data Loading: Load data that updates in real-time or on demand
• Synthetic Overlays: Generate overlays programmatically (grids, graticules)
• Data Providers: Fetch data from third-party services

Overlay Display

Plugins that change how overlay data is visualized:

• Markers & Renderers: Custom marker styles, WebGL rendering, special symbols
• Overlay Animations: Animate markers along paths or through time
• Clustering/Decluttering: Group nearby markers to reduce visual clutter
• Heatmaps: Display point density as gradient overlays
• DataViz: Add charts, graphs, or other data visualizations to the map

Map Interaction

Plugins that modify user interaction with the map:

• Layer Switching Controls: Enhanced layer control panels
• Pan/Zoom Controls: Alternative navigation interfaces (joysticks, mini-maps)
• Measurement Tools: Measure distances, areas, or bearings
• Print/Export: Generate images or PDFs of the map
• Fullscreen: Toggle fullscreen mode
• Geolocation: Enhanced location tracking

Plugin Database System

The plugin database is a Jekyll-based system that generates the plugin listing page from individual plugin metadata files.

Database Architecture

100%

Plugin Metadata Schema

Each plugin is defined by a markdown file in docs/_plugins/ with YAML front matter:

---
name: Plugin Name
category: basemap-providers
repo: https://github.com/user/repo
author: Author Name
author-url: https://github.com/user
compatible-v1: true
compatible-v2: true
demo: https://user.github.io/repo/demo
---
Plugin description goes here.

The plugin_category_table.html template filters plugins by category and generates tables with the following columns:

Column	Source	Description
Plugin	plugin.name, plugin.repo	Plugin name linking to repository
Description	plugin.content	Plugin description from markdown body
V1	plugin.compatible-v1	Checkmark if compatible with Leaflet v1.x
V2	plugin.compatible-v2	Checkmark if compatible with Leaflet v2.x
Demo	plugin.demo	Link to live demo if available
Maintainer	plugin.author, plugin.author-url	Plugin author with optional link

Repository Badge System

The plugin listing page includes JavaScript that dynamically loads repository statistics:

100%

The badge system uses regular expressions to extract repository information from plugin URLs:

• GitHub.com pattern: /^https?:\/\/(?:www\.)?github\.com\/([\w\d-_.]+)\/([\w\d-_.]+)\/?/
• GitHub.io pattern: /^https?:\/\/([\w\d-_.]+)\.github\.io\/([\w\d-_.]+)\/?/
• GitLab.com pattern: /^https?:\/\/(?:www\.)?gitlab\.com\/([\w\d-_.]+)\/([\w\d-_.]+)\/?/

Table Sorting

The plugin tables support client-side sorting by clicking column headers. The sorting implementation handles:

• Text and numeric values
• Empty cells (sorted to the end)
• Ascending/descending toggle via data-sort-dir attribute

Plugin Development Workflow

Creating a Plugin

The plugin development process follows these general steps:

100%

Plugin Guidelines

Plugin developers are encouraged to follow the recommendations in the plugin guide:

• Repository: PLUGIN-GUIDE.md in the Leaflet repository provides detailed guidelines
• Key Recommendations:
  • Keep plugins in individual repositories (not collections)
  • Follow Leaflet's coding style and patterns
  • Support both ESM and UMD builds
  • Document compatibility with Leaflet versions
  • Provide live demos
  • Use semantic versioning

Submission Process

To add a plugin to the official database:

1. Create Plugin File: Add a markdown file to docs/_plugins/ with YAML front matter
2. Include Metadata: Specify category, repository URL, author, compatibility, demo link
3. Write Description: Add a brief description in the markdown body
4. Submit Pull Request: Send PR to the Leaflet GitHub repository
5. Review Process: Maintainers review for completeness and appropriateness

The plugin will appear on the plugins page after the PR is merged and the site is rebuilt.

Plugin Integration Examples

Layer Plugin Pattern

Layer plugins extend L.Layer or one of its subclasses:

// Plugin extends L.TileLayer to add custom functionality
L.CustomTileLayer = L.TileLayer.extend({
    initialize: function(url, options) {
        L.TileLayer.prototype.initialize.call(this, url, options);
        // Custom initialization
    },
    
    createTile: function(coords, done) {
        // Custom tile creation logic
        var tile = document.createElement('img');
        // ... custom tile loading
        return tile;
    }
});

// Factory function
L.customTileLayer = function(url, options) {
    return new L.CustomTileLayer(url, options);
};

Common layer plugin integration points:

• initialize(): Constructor logic
• onAdd(map): Called when layer is added to map
• onRemove(map): Called when layer is removed from map
• getEvents(): Return map events to listen to

Related: See Layer Base Class for lifecycle methods, Tile Layers and Grid System for tile-specific extension points.

Control Plugin Pattern

Control plugins extend L.Control to add UI elements:

// Plugin extends L.Control for custom UI widget
L.Control.CustomControl = L.Control.extend({
    options: {
        position: 'topright'
    },
    
    onAdd: function(map) {
        var container = L.DomUtil.create('div', 'custom-control');
        // Build UI in container
        return container;
    },
    
    onRemove: function(map) {
        // Cleanup
    }
});

// Factory function
L.control.customControl = function(options) {
    return new L.Control.CustomControl(options);
};

Related: See Controls for control positioning and lifecycle.

Handler Plugin Pattern

Handler plugins extend L.Handler to add interaction modes:

// Plugin extends L.Handler for custom interaction
L.Map.CustomHandler = L.Handler.extend({
    addHooks: function() {
        // Add event listeners when enabled
        L.DomEvent.on(this._map._container, 'click', this._onClick, this);
    },
    
    removeHooks: function() {
        // Remove event listeners when disabled
        L.DomEvent.off(this._map._container, 'click', this._onClick, this);
    },
    
    _onClick: function(e) {
        // Handle click
    }
});

// Add to map prototype
L.Map.addInitHook('addHandler', 'customHandler', L.Map.CustomHandler);

Related: See Map Interaction Handlers for handler patterns and the Handler base class.

Utility Plugin Pattern

Utility plugins add helper functions to the L namespace:

// Plugin adds utility functions
L.Util.customFunction = function(input) {
    // Custom logic
    return result;
};

// Or add a namespace
L.CustomUtil = {
    method1: function() { },
    method2: function() { }
};

Plugin Distribution Channels

Plugins are distributed through multiple channels:

Channel	Purpose	Discovery Method
Official Plugin Database	Curated list on leafletjs.com	Browse categorized tables, search page
npm Registry	Package manager distribution	npm search leaflet-plugin
GitHub Topics	Community discovery	GitHub topic: leaflet-plugin
CDN Services	Direct script inclusion	jsDelivr, unpkg, cdnjs

The official plugin database serves as the primary discovery mechanism, while npm provides the standard distribution method for modern JavaScript applications.

Version Compatibility

Plugins must declare compatibility with Leaflet versions:

• V1 Compatibility: Plugin works with Leaflet 1.x (current stable)
• V2 Compatibility: Plugin works with Leaflet 2.x (upcoming major version)

The plugin database displays checkmarks for each compatible version, helping users select appropriate plugins for their Leaflet version. Breaking changes between major versions may require plugin updates.

Related: See Version History and Migration for details on version differences.

This plugin system enables Leaflet's extensibility while maintaining a lightweight core. The categorized database, clear extension points, and standardized submission process create a thriving ecosystem of hundreds of community-maintained plugins.