Leaflet
Advanced Drupal integration with the Leaflet JS mapping library for displaying and editing geographic data.
leaflet
Install
composer require 'drupal/leaflet:^10.3'
Overview
The Leaflet module provides comprehensive integration with the Leaflet JavaScript library, enabling interactive web mapping capabilities in Drupal. It allows content editors to create, edit, and display geographic data through intuitive map interfaces.
The module offers a Geofield widget with drawing tools (powered by Leaflet-Geoman), a formatter for displaying locations on maps, and full Views integration for creating map-based content listings. It supports multiple tile layer providers, marker clustering, tooltips, popups, geocoding search, and extensive customization through tokens and hooks.
Features include vector tile support via MapLibre GL JS, GeoJSON overlay integration for precision drawing, fullscreen mode, user location detection, and lazy loading for performance optimization.
Features
- Interactive Leaflet Map Widget with Leaflet-Geoman drawing tools for creating and editing Points, LineStrings, Polygons, Circles, and Rectangles
- Leaflet Map Field Formatter for displaying geofield data as interactive maps with customizable markers, popups, and tooltips
- Full Views integration with Leaflet Map style plugin for displaying any View as an interactive map with overlays and layer controls
- Support for multiple base tile layers including OpenStreetMap, Stadia Maps, Google Maps, MapTiler, and custom providers
- Vector tile support via MapLibre GL JS integration for high-performance map rendering
- Marker clustering functionality through the Leaflet Markercluster submodule for handling large numbers of markers
- GeoJSON overlay integration allowing external and internal sources as reference layers for precision drawing with snapping
- Dynamic marker icons supporting custom images, SVG, HTML DivIcons, and Circle Markers with token-based customization
- Leaflet Tooltips and Popups with configurable content using tokens, entity fields, or rendered view modes
- Address search geocoding with autocomplete integration (requires Geocoder module)
- User location detection via Leaflet.Locate plugin
- Fullscreen map control via Leaflet.Control.FullScreen plugin
- Reset Map View control for returning to initial map position
- Map Scale control for displaying distance scale
- Gesture handling for improved touch device interaction
- Lazy loading using IntersectionObserver API for performance optimization
- Token and replacement pattern support in all map component settings
- Extensive hook system for customizing map definitions, features, and rendering
- Search API Views integration for displaying indexed content on maps
- AJAX popup loading for improved performance with entity view modes
- Overlays grouping through Views field grouping for layer control management
Use Cases
Store Locator Map
Create a content type for store locations with a geofield. Use Leaflet Views to display all stores on an interactive map with clustering for dense areas. Configure popups to show store details and use the geocoder for users to search by address.
Event Location Editor
Add a geofield to an event content type with the Leaflet widget. Enable drawing tools for precise location marking. Use GeoJSON overlays from a separate field containing venue boundaries for snapping to predefined locations.
Property Listings Map
Build a real estate site with property locations displayed on a Leaflet map View. Use token-based icons to show different markers for property types. Enable marker clustering and AJAX popups for performance with thousands of listings.
Multi-Layer Geographic Dashboard
Create a View with grouping by category field to display different types of locations as separate overlay layers. Users can toggle layers on/off using the layer control. Combine with Leaflet attachment displays for additional data layers.
Trail/Route Mapping
Use the Leaflet widget to draw LineString/Polygon geometries for hiking trails or delivery routes. Configure path styling options for visual differentiation. Display routes on maps with the formatter using custom path colors based on difficulty tokens.
Interactive Data Visualization
Leverage the multiple tile layer support and vector tiles via MapLibre GL JS for data-rich map visualizations. Use feature additional properties to pass custom data to JavaScript for advanced interactivity through hooks.
Tips
- Use hook_leaflet_map_info() to define custom map presets with different tile providers that can be selected in widget/formatter settings
- Token replacement supports field values, entity properties, and site tokens - use the token browser to explore available options
- For better performance with many markers, enable marker clustering and consider AJAX popup loading for entity view modes
- GeoJSON overlays in the widget support snapping - ideal for drawing points precisely on reference geometries like building outlines
- Vector tiles via MapLibre GL JS provide smoother zooming and rotation for modern base maps supporting vector formats
- Use the feature_properties JSON field to pass custom data to JavaScript for advanced interactivity via hooks
- The lazy load option improves initial page load when maps are below the fold - maps initialize when scrolled into view
- Overlay grouping in Views allows users to toggle feature categories on/off - use a taxonomy or list field for grouping
- Custom CSS classes on markers (with token support) enable styling markers differently based on entity data
Technical Details
Permissions 1
Hooks 10
hook_leaflet_map_info
Define custom map definitions with tile layers, settings, and default configurations
hook_leaflet_map_info_alter
Alter existing map definitions to modify tile layers, settings, or add custom icons
hook_leaflet_default_widget_alter
Alter the Leaflet Map Widget settings before rendering
hook_leaflet_formatter_feature_alter
Alter individual Leaflet features/markers in the formatter before rendering
hook_leaflet_default_map_formatter_alter
Alter the entire Leaflet Map Formatter settings and features
hook_leaflet_map_view_geofield_value_alter
Alter geofield values in Views before processing
hook_leaflet_views_feature_alter
Alter individual features/markers in Leaflet Views
hook_leaflet_views_features_alter
Alter all features array in Leaflet Views before rendering
hook_leaflet_views_features_group_alter
Alter feature groups (overlays) in Leaflet Views
hook_leaflet_map_view_style_alter
Alter the entire Leaflet Map View Style settings
Troubleshooting 6
Check browser console for JavaScript errors. Ensure the Leaflet library is properly installed (check status report at /admin/reports/status). Verify the map container has a defined height. Clear Drupal caches.
Verify icon URL paths are accessible and absolute. Check that icon sizes are specified (module can auto-detect from image if URL is valid). Ensure file permissions allow web access to icon images.
Confirm Geocoder module is installed and configured with at least one provider. Check that the user has 'access geocoder api endpoints' permission. Verify provider API keys are configured if required.
Ensure at least one geofield is added to View fields and selected as Data Source in the Leaflet Map style settings. Check that the geofield contains valid WKT data. Verify View is returning results.
Ensure token patterns are correct (use the token browser). Check that the entity has values for the referenced fields. For Views, make sure the replacement field is added to the View fields.
Enable the Leaflet Markercluster submodule. Check that clustering is enabled in the formatter/View settings. Ensure there are multiple markers in close proximity to trigger clustering.
Security Notes 4
- The 'configure leaflet' permission controls access to see module administrative warnings - assign appropriately
- Geocoder functionality requires 'access geocoder api endpoints' permission to prevent unauthorized API usage
- Token replacement in popups/tooltips uses proper sanitization but review custom content for XSS risks
- External tile providers may log user IP addresses - review privacy implications of chosen map providers