OSM Map Block

OSM Map Block adds the dynamic Gutenberg block osm-map/map to WordPress. It displays an interactive OpenStreetMap using MapLibre GL JS and OpenFreeMap vector tiles. The plugin stores map settings as block attributes and does not use an iframe or require an API key.

Requirements

• WordPress 6.5 or newer
• PHP 7.4 or newer
• A browser with WebGL support
• Public network access to the configured map provider

Main features

• Set a map center by dragging the editor map or entering a Geo URI.
• Set zoom with the map controls or a Geo URI.
• Add, select, edit, and remove multiple markers.
• Drag markers directly on the editor map.
• Choose a marker icon, color, size, and accessible name.
• Use normal, wide, or full block alignment.
• Use WordPress aspect-ratio controls; the default is 16:9.
• Render validated map data on the server.
• Show an OpenStreetMap link when the interactive map cannot load.
• Load frontend scripts and styles only when the block is rendered.

Installation

1. Copy this directory to wp-content/plugins/osm-map-block.
2. Activate OSM Map Block in Plugins in WordPress admin.
3. Add the OpenStreetMap block in the block editor.

No Composer, npm, or build step is required. MapLibre 6.6.0 and its worker files are included under assets/maplibre/.

Setting a location

New blocks use latitude 52.0087, longitude 4.71191, and zoom 13. Move or zoom the editor map, or enter one of these supported Geo URI forms:

geo:52.0087,4.71191
geo:52.0087,4.71191?z=16

Press Enter or leave the field to apply it. Without z, the current zoom is retained. The plugin accepts two-dimensional WGS-84 coordinates and the z extension. Altitude, crs, uncertainty, and other parameters are not supported. Invalid input leaves the last valid map visible.

Coordinates are stored to eight decimal places and zoom to two. Existing blocks created with the older OpenStreetMap URL input retain their coordinates and receive a Geo URI when edited. Scroll-wheel zoom, rotation, and pitch are disabled.

Markers

Use the Markers panel in the block sidebar. New markers start at the map center. Each marker supports:

• Latitude and longitude
• Plain-text accessible name
• Location, circle, star, flag, or information icon
• Small, medium, or large size
• A hexadecimal color from the theme or fallback palette

Marker coordinates are applied when pressing Enter or leaving the field. Invalid values keep the last valid position. Markers are icon-only: they do not provide popups, links, or uploaded images. Moving a marker does not change the saved map center or zoom.

PHP validates coordinates, IDs, labels, icons, colors, and sizes again before rendering. Blocks saved before marker support continue to work.

Map provider and style

The default MapLibre style is assets/default-style.json. It uses the OpenMapTiles schema, OpenFreeMap tiles and glyphs, and visible OpenFreeMap, OpenMapTiles, and OpenStreetMap attribution. OpenFreeMap is keyless but does not provide a service-level guarantee.

The style must retain the vector source ID openmaptiles, which the plugin uses to apply the configured TileJSON source and attribution. Edit a copied style with Maputnik and keep MapLibre Style Specification version 8.

Trusted configuration filters

Provider settings are controlled through PHP filters, not block attributes:

add_filter( 'osm_map_style_url', function () {
    return get_theme_file_uri( 'assets/maps/style.json' );
} );

add_filter( 'osm_map_tile_source', function () {
    return 'https://maps.example.org/tiles/tiles.json';
} );

add_filter( 'osm_map_attribution', function () {
    return '<a href="https://www.openstreetmap.org/copyright">OpenStreetMap contributors</a>';
} );

add_filter( 'osm_map_default_view', function () {
    return array(
        'latitude'  => 52.0087,
        'longitude' => 4.71191,
        'zoom'      => 13,
    );
} );

When changing providers, preserve every required data, style, and provider attribution. A provider with different glyphs, sprites, or source-layer names also needs a compatible copy of default-style.json.

Code overview

• osm-map-block.php: plugin registration, defaults, filters, and validation
• block.json: block metadata, attributes, assets, and supported controls
• render.php: accessible server-rendered map markup and fallback link
• src/editor.js: Gutenberg controls and saved attribute updates
• src/frontend.js: frontend map startup
• src/map-runtime.js: shared MapLibre setup, controls, and marker rendering
• assets/: plugin styles, map style, and vendored MapLibre files

Multiple blocks on one page share the fetched style through an in-page cache.

Development checks

There is currently no automated test suite. Lint both PHP files and manually test the block editor and frontend after changes:

ddev exec php -l public_html/wp-content/plugins/osm-map-block/osm-map-block.php
ddev exec php -l public_html/wp-content/plugins/osm-map-block/render.php
git diff --check

Test Geo URI validation, map movement, marker editing and dragging, multiple maps, responsive sizing, fallback behavior, and existing blocks without markers.

License

The plugin is licensed under GPL-2.0-or-later. Vendored MapLibre GL JS is licensed under BSD-3-Clause; see assets/maplibre/LICENSE.txt.