CartoBlocks for Leaflet

CartoBlocks for Leaflet adds a native Gutenberg block that wraps the Leaflet Map plugin shortcodes. Configure your map visually in the block editor — the plugin generates the correct shortcodes automatically, and the frontend is rendered entirely by Leaflet Map.

Core map features:

• Interactive live preview in the editor — what you see is what you get.
• Pan, zoom, and drag markers directly on the map preview.
• Sidebar controls for coordinates, zoom level, height, width, and scroll-wheel zoom.
• Address geocoding — search by place name (Nominatim/OpenStreetMap), pick from up to 5 candidates.
• Fit map to markers toggle.
• Full tile layer override: custom tile URL, tile size, subdomains, Map ID, access token, zoom offset, no-wrap, detect retina.
• WMS tile source support ([leaflet-wms]) — toggle in Tile Layer panel; configure source URL, layer name, and CRS.
• Image map mode ([leaflet-image]) — replace tiles with a flat image (floor plans, diagrams, custom maps) on L.CRS.Simple.
• Map Controls panel: min/max zoom, max bounds, scale bar, custom attribution.
• Interaction controls: dragging, keyboard, double-click zoom, box zoom, close-popup-on-click, tap, inertia — each with Default / Enabled / Disabled three-state model.

Markers ([leaflet-marker]):

• Add, edit, and remove markers with title and popup content (HTML supported).
• Per-marker: alt text, auto-open popup, draggable, opacity, z-index offset.
• Custom icon via WordPress Media Library — width/height with aspect-ratio lock, icon anchor and popup anchor with 9-position presets.
• SVG marker mode — background color, icon color (theme palette + custom picker), icon CSS class (Font Awesome / any icon font).
• Per-marker address geocoder.
• Drag markers on the live preview to update coordinates in real time.

Lines and polygons ([leaflet-line]):

• Click-to-draw lines and polygons directly on the map preview.
• Per-line/polygon: color, weight, opacity, dash array, CSS class, fill, fill color, fill opacity, popup text.
• Per-point address geocoder.

Circles ([leaflet-circle]):

• 2-click draw on the map preview — first click places center, second click sets radius.
• Live radius guide line and draggable center pin post-draw.
• m/km unit toggle (stored in meters).
• Per-circle: color, weight, opacity, dash array, CSS class, fill, fill color, fill opacity, popup text.
• Per-circle address geocoder.

Data layers ([leaflet-geojson], [leaflet-gpx], [leaflet-kml]):

• Load external GeoJSON, GPX, or KML files by URL.
• Full attribute parity: fitbounds, popup template with {property} interpolation, popup property, table view.
• Style controls: color, weight, opacity, dash array, CSS class, fill, fill color, fill opacity.
• Custom point icon with aspect-ratio lock and anchor presets.

Image and video overlays ([leaflet-image-overlay], [leaflet-video-overlay]):

• Pin raster images or videos to geo coordinates via SW/NE bounds.
• Controls: opacity, interactivity, alt text, z-index, CSS class.
• Aspect-ratio lock for image overlays.

Developer-friendly:

• Generates standard Leaflet Map shortcodes — full compatibility with the Leaflet Map plugin ecosystem.
• Multiple independent map blocks per page, fully isolated.
• Shortcode viewer in the toolbar — inspect and copy the generated shortcode at any time.
• All strings are translation-ready (.pot file included).

Requirements:

• The Leaflet Map plugin must be installed and active. This is declared as a plugin dependency, so WordPress will guide you to install and activate it before this plugin can be activated.
• WordPress 6.8 or higher.
• PHP 7.4 or higher.

Source Code

The JavaScript and CSS files shipped in the build/ directory of this plugin are compiled with webpack (via @wordpress/scripts): the JavaScript from the JSX sources and the CSS from the SCSS sources. The human-readable source code is publicly available in the plugin’s development repository:

https://github.com/jesusyesares/cartoblocks-for-leaflet

The uncompiled sources (.js and .scss) live in the src/ directory of that repository. To build the plugin from source:

1. Clone the repository: git clone https://github.com/jesusyesares/cartoblocks-for-leaflet.git
2. Install the dependencies: npm install
3. Build the production files into build/: npm run build

External services

This plugin connects to one external service: the Nominatim geocoding API operated by the OpenStreetMap Foundation. It is used only in the block editor, and only when you click the address search button to look up the coordinates of a place name. It is never called on the frontend of your site and is never called automatically.

When you perform an address search, the text you type into the search field is sent to https://nominatim.openstreetmap.org/search so it can be matched against OpenStreetMap data and returned as a list of candidate locations. The request also includes your site URL and administrator contact email in the User-Agent header, following Nominatim’s usage policy for attribution. No other personal data is transmitted. If you have configured a Nominatim contact email in the Leaflet Map plugin settings, that value is used instead.

• Service provider: OpenStreetMap Foundation (Nominatim)
• Terms / usage policy: https://operations.osmfoundation.org/policies/nominatim/
• Privacy policy: https://wiki.osmfoundation.org/wiki/Privacy_Policy

Note: GeoJSON, GPX, and KML data layers, and any map tiles, are loaded by the Leaflet Map plugin (and your browser) from whatever URLs you enter. Those requests are made by the Leaflet Map plugin, not by CartoBlocks for Leaflet.

Note: if “Use WMS tile source” is enabled but the WMS Source field is left empty, the Leaflet Map plugin falls back to a free public demo WMS service operated by terrestris GmbH (ows.mundialis.de). That service displays a watermark and is also a third-party request — provide your own WMS URL to avoid it.

Known Limitations

GPX data layers from the Media Library may not render.

When a .gpx file is uploaded to the WordPress Media Library and used as the source of a GPX data layer, the track may fail to draw, while GeoJSON and KML layers work in the same setup. This is an upstream limitation in the Leaflet Map plugin, not in CartoBlocks for Leaflet: its GeoJSON/GPX/KML loader reads the response as XML (responseXML), which the browser only populates when the file is served with an XML Content-Type (text/xml, application/xml, or a +xml subtype). Many web servers serve .gpx as text/plain or application/octet-stream, so the track is never parsed. The same behaviour occurs when using the Leaflet Map plugin’s [leaflet-gpx] shortcode directly.

Workarounds: serve the GPX file from a host that sets an XML Content-Type (e.g. application/gpx+xml), or configure your web server to serve .gpx as XML. GeoJSON and KML layers are unaffected.

Check out the source code and more details on GitHub!