GPX Route Map

GPX Route Map turns a GPX file into an interactive map on the front end of your site. gpx file, and visitors get:

• An interactive map powered by MapLibre GL, on OpenStreetMap, OpenTopoMap or Thunderforest tiles.

• 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.

• Optional Waypoint posts (experimental), to give a waypoint its own description, a photo shown as its marker, or an icon in your own colors.

• A stats bar: distance, elevation gain, elevation loss, max and min 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.

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). 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. The block editor’s map preview loads tiles the same way, from the browser of whoever is editing the post.

No data is sent when a page has no map on it, and the plugin never sends your GPX files anywhere.

OpenStreetMap (default)

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)

com instead, and your API key is included in each tile request. This only happens once a Thunderforest style is chosen and a key supplied; 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.

OpenTopoMap (optional)

org instead. No account or key is needed. This only happens once OpenTopoMap is chosen; the plugin never contacts it otherwise.

OpenTopoMap is run by volunteers, with no guarantee that it stays available, and its maps have less detail close in than OpenStreetMap’s.

Service: OpenTopoMap. Terms: Usage terms (in German). Privacy: OpenTopoMap publishes no privacy policy; its operator is named in the imprint.

Any other provider

If a developer points the plugin at another tile server with the gpxrm_tile_url filter, the same applies to whichever server that is.

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" 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: the site setting.

• height_tablet – Map height at 782px and below. Default: the site’s Tablet height, or height when the site sets none.

• height_mobile – Map height at 480px and below. Default: the site’s Mobile height, or height_tablet when the site sets none.

• 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 – How close the map opens when it frames a short route, from 1 to 22, though never closer than its tile provider has tiles. Visitors can zoom in as far as those tiles go. Default: the site setting.

• provider – The map tiles: osm (OpenStreetMap), opentopomap, or a Thunderforest style once its API key is saved: thunderforest-outdoors, thunderforest-cycle, thunderforest-landscape or thunderforest-atlas. A Thunderforest style without a saved key shows the site’s provider. Default: the site setting.

• units – metric (km / m) or imperial (mi / ft). Default: the site setting.

• fields – Which stats to list, from distance, gain, loss, max, min and waypoints, e.g. distance,gain. Default: the site setting. Use stats="false" to remove the bar.

• waypoints – Link the file’s waypoints to Waypoint posts, as number:post ID pairs that number the waypoints from 1 in the order of the file, e.g. 1:12, 3:40. Needs Waypoint posts turned on. Default: only the links the GPX file holds, when it is in the Media Library.

Provide either id or gpx. The block exposes the same options in its sidebar (Source, Display, Stats bar items and Map tiles panels, and Waypoints once Waypoint posts are on).

Filters (for developers):

• gpxrm_tile_url – change the raster tile URL template a map loads. It runs for every map, whether its provider comes from the block, the shortcode or the site setting. The second argument is the provider that map uses, such as osm, opentopomap or thunderforest-outdoors: its own choice, else the site’s, else osm while a Thunderforest style has no key. A callback that ignores the second argument replaces the tiles of every map, whatever was chosen for it.

• gpxrm_tile_max_zoom – change the last zoom level a tile server has tiles for (integer, 0 for not known), such as for a tile server of your own; the second argument is the tile URL template.

• gpxrm_tile_attribution – change the attribution HTML.

• gpxrm_height – change the site-wide map height in pixels (integer).

• gpxrm_max_zoom – change how close maps open when they frame a short route, site-wide (integer).

• gpxrm_heights – change the site-wide height for every viewport band (array of base, tablet, mobile; 0 means “follow the next larger band”).

• 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, min, waypoints ).