PanMap

Description

A standard embedded Google Map starts downloading Google’s entire map application – scripts, styles, fonts and map tiles – the moment your page loads, whether or not anyone ever looks at it. That work competes with your own content and drags down your Core Web Vitals.

PanMap takes that cost off the initial page load. It shows a clean, lightweight placeholder where the map will be, and only loads the real, interactive Google Map once it scrolls into a visitor’s view.

Built for performance

• Zero requests to Google on page load. The placeholder is drawn with inline SVG and CSS served from your own site. Nothing is fetched from Google until the map scrolls into view.
• Tiny footprint. About 4 KB of CSS and 2 KB of JavaScript, and neither file loads on pages that don’t contain a map.
• No flash of empty space. The placeholder stays in view until the real map has finished loading, then cross-fades smoothly into it.

No API key, no billing

PanMap uses Google’s keyless map embeds, so there is no Google Cloud project, API key or billing account to set up.

Easy to set up

• Find any location. Type a place name or address, enter coordinates, or paste a link copied from Google Maps – including “Share” links.
• Or use the exact map you made in Google Maps. Paste the code from Google Maps’ Share > Embed a map, and PanMap lazy-loads that same map.
• See it before you publish. Preview the placeholder and the real, interactive map exactly as your visitors will see them.
• Copy and paste. PanMap writes the shortcode for you.

Thoughtfully built

• Accessible. There is nothing to click or tab to – the map loads on its own as it scrolls into view, and the cross-fade respects the “reduce motion” system setting.
• Works without JavaScript. Visitors with JavaScript disabled still get a working map.
• Works with page builders. Maps added to the page after it loads, for example by Ajax or a page builder’s live preview, work without extra setup.
• Translation-ready.

Every feature described here is included in this plugin. Nothing is locked.

Usage

Go to PanMap in your admin menu, add a map, then click Copy shortcode and paste it into any post, page or widget that supports shortcodes. The shortcode it copies points at the saved map, so editing that map later updates every place the shortcode is already pasted:

[panmap slug="our-office"]

You can also write a map out by hand, without saving it first:

[panmap address="India Gate, New Delhi" title="Our Office"]

[panmap lat="28.6129" lng="77.2295" zoom="17"]

Shortcode attributes

• slug – The name of a map saved on the PanMap screen. Takes over completely: every other attribute is ignored. This is what Copy shortcode writes.
• embed – The map details from Google Maps’ “Embed a map” code. The PanMap screen fills this in when you paste that code. Takes priority over everything below.
• lat – Latitude, from -90 to 90. Use with lng. Takes priority over address.
• lng – Longitude, from -180 to 180. Use with lat.
• address – Any place name or address Google Maps can find.
• zoom – Zoom level, from 1 (whole world) to 21 (individual buildings). Defaults to the value on the settings screen, or 15. Not used with embed, which keeps its own zoom.
• title – The location’s name, used as the map’s accessible title once it loads. Optional.
• height – Map height in pixels, from 120 to 1200. Defaults to the value on the settings screen, or 400.

Out-of-range zoom and height values are clamped to the nearest allowed value. If there is no usable location, the shortcode outputs nothing rather than a broken map.

External services

This plugin uses Google Maps, a service provided by Google LLC, to show interactive maps of the locations you choose.

On your site’s front end: only once a map placeholder scrolls into a visitor’s view, their browser loads the map from Google Maps (maps.google.com or www.google.com). That request includes the map’s location – its address, its latitude and longitude, or the embed details copied from Google Maps – and its zoom level. Like any request to a third-party website, it also sends Google the visitor’s IP address and browser information, and Google may set or read cookies. No request is made to Google before that. If a visitor has JavaScript disabled, the map is embedded directly instead, using the browser’s own native lazy-loading, and the same request is made when it scrolls into view.

On the PanMap admin screen: when an administrator previews a map, their browser loads it from Google Maps in the same way. When an administrator pastes a Google Maps “Share” link (maps.app.goo.gl) and presses Find, your web server sends that link to Google to look up the location it points to. Only the link itself is sent.

This service is subject to Google’s terms and privacy policy:

• Google Maps/Google Earth Additional Terms of Service
• Google Terms of Service
• Google Privacy Policy

This plugin also uses OpenStreetMap, a service of the OpenStreetMap Foundation, on the PanMap admin screen only. When an administrator opens “Pin it on a map instead” to set a location by hand, their browser loads map tile images from OpenStreetMap’s tile servers (tile.openstreetmap.org) so they can click to place a pin. This sends OpenStreetMap the administrator’s IP address and browser information, the same as any request to a third-party website. No account, API key or payment is required, and this never happens on the site’s front end or without the admin screen being open.

This service is subject to OpenStreetMap’s terms and privacy policy:

• OpenStreetMap Foundation Privacy Policy
• Tile Usage Policy

Source code

Nothing in this plugin is obfuscated, and no compiled file ships without the source it was built from. The download contains its own complete source:

• src/index.js and src/index.scss build the admin screen – build/index.js and build/index.css.
• src/frontend.js and src/frontend.scss build the front end – build/frontend.js and build/frontend.css.
• src/components/ and src/shared/ hold the rest of the admin screen’s code.
• Everything in includes/ is plain, readable PHP that runs as-is.

To rebuild the compiled files, you need Node.js 20 or newer. From the plugin folder:

npm install
npm run build

That runs @wordpress/scripts 35 (webpack), which writes build/. npm run dist additionally runs gulpfile.js to assemble a release copy of the plugin in dist/.

Third-party libraries

• Leaflet 1.9.4, by Volodymyr Agafonkin, BSD-2-Clause licensed – source at github.com/Leaflet/Leaflet. It is compiled into build/index.js, its stylesheet into build/index.css, and its default marker images are the files in build/images/. Leaflet draws the “Pin it on a map instead” picker on the admin screen only; it never loads on the front end.

Leaflet’s copyright notice and license text are reproduced in LICENSE.txt, alongside PanMap’s own GPLv2 license.

No other third-party library is bundled. Everything else the admin screen uses – React, the components, the data layer – comes from the copies WordPress itself ships.

Technical details