GPX Route Map

GPX Route Map turns a GPX file into an interactive map on the front end of your site. Drop the block into any post or page, pick a .gpx file, and visitors get:

• An interactive OpenStreetMap map powered by MapLibre GL.
• The track drawn as a route line with start and end markers.
• Support for both GPX tracks (<trk>) and GPX routes (<rte>), e.g. Garmin Connect course exports.
• Waypoint markers with popups for any <wpt> points in the file.
• A stats bar: distance, elevation gain, elevation loss and max elevation, in metric or imperial units.
• A hand-drawn elevation profile you can scrub with mouse or touch, the position syncs onto the map.

The map loads lazily (only when it scrolls into view) so it never slows down your page, and multiple maps can live on the same page.

You can author tracks in any GPX tool, for example the free gpx.studio editor, then upload the resulting file to your Media Library.

Source code

The front-end JavaScript in build/ is minified (the block editor script is not, so that its strings stay translatable). The human-readable source lives in the plugin’s src/ directory, which is included in this plugin, and is also available with full build instructions at the public repository: https://github.com/SirLouen/gpx-route-map. The plugin is built with Vite (pnpm install && pnpm run build).

External services

This plugin renders maps using map images (tiles) served by a third party. Tiles are loaded directly by each visitor’s browser when a page containing a map is viewed, so the tile provider receives that visitor’s IP address, browser User-Agent, and the coordinates of the map area being viewed. No data is sent when a page has no map on it, and the plugin never sends your GPX files anywhere.

OpenStreetMap (default)

Out of the box the plugin uses OpenStreetMap’s public tile server at tile.openstreetmap.org. No account or key is needed, and nothing has to be configured.

Service: OpenStreetMap. Terms: Tile Usage Policy. Privacy: OSMF Privacy Policy.

The public OSM tile server is rate-limited and is not intended for high-traffic sites.

Thunderforest (optional)

If you choose Thunderforest under Settings > GPX Route Map and enter an API key, tiles are loaded from api.thunderforest.com instead, and your API key is included in each tile request. This only happens once you have selected Thunderforest and supplied a key; the plugin never contacts them otherwise.

Because visitors’ browsers load the tiles, the key is visible in your pages’ source. Thunderforest does not offer a way to restrict a key to your domain, so treat the key as public and keep an eye on your usage.

Service: Thunderforest. Terms: Thunderforest Terms and Conditions. Privacy: Thunderforest Privacy Policy.

Any other provider

If you set a custom tile URL of your own, the same applies to whichever server that URL points at.

Usage

Block: search for “GPX Route Map” in the block inserter, then choose a GPX file.

Shortcode: [gpx_route_map]

Examples:

[gpx_route_map id="123"] - render the GPX attachment with ID 123.
[gpx_route_map gpx="https://example.com/route.gpx" height="520" elevation="false"]

Shortcode attributes:

• id – Attachment ID of a .gpx file uploaded to the Media Library.
• gpx – Attachment ID, or an absolute URL to a .gpx file (alternative to id).
• height – Map height in pixels, from 200 to 1200. Default: 480.
• stats – Show the stats bar (distance, elevation, waypoints). true or false. Default: the site setting.
• elevation – Show the interactive elevation profile. true or false. Default: the site setting.
• download – Show the GPX download button on the map. true or false. Default: the site setting (off).
• maxzoom – Maximum zoom level, from 1 to 22. Default: 17.
• tile – Custom raster tile URL template using {z}/{x}/{y}. Default: OpenStreetMap.
• units – metric (km / m) or imperial (mi / ft). Default: the site setting.
• fields – Which stats to list, e.g. distance,gain. Default: the site setting. Use stats="false" to remove the bar.

Provide either id or gpx. The block exposes the same options in its sidebar (Source, Display and Map tiles panels).

Filters (for developers):

• gpxrm_tile_url – change the default raster tile URL template.
• gpxrm_tile_attribution – change the attribution HTML.
• gpxrm_units – change the site-wide unit system (metric or imperial).
• gpxrm_show_stats – change whether the stats bar shows by default (boolean).
• gpxrm_show_elevation – change whether the elevation profile shows by default (boolean).
• gpxrm_show_download – change whether the download button shows by default (boolean).
• gpxrm_stat_fields – change which stats the bar lists by default (array of distance, gain, loss, max, waypoints).