Putting a map on a Joomla site sounds like a five-minute job, and sometimes it is. But the Google Maps landscape has shifted enough over the years — API keys became mandatory, billing accounts entered the picture, privacy regulators started caring about embedded third-party scripts — that the "right" way to add a map depends on what you actually need it to do. A contact page for a single office has very different requirements than a store locator with forty markers.
We have wired maps into Joomla sites in every way imaginable: raw iframe embeds, dedicated map modules, the JavaScript API with custom markers, and plain static images. Each approach has a cost in setup time, page weight and long-term maintenance. This article walks through all of them so you can pick the lightest tool that does the job.
The simplest option: an iframe embed in a Custom HTML module
For the classic use case — "show where our office is on the contact page" — you do not need a map extension at all. Google gives every place and address a free, keyless embed code:
- Open Google Maps in your browser and search for your business or address.
- Click Share, then the Embed a map tab, and copy the iframe code.
- In Joomla, create a Custom HTML module and paste the iframe into it.
- Assign the module to a position on your contact page and publish it.
The only Joomla-specific hurdle is the WYSIWYG editor, which loves to strip iframes when you save. You either relax the editor's filtering options or switch your editor to None before pasting. We cover that dance in detail in our guide on how to create a Custom HTML module in Joomla — the same technique applies to any embed code, not just maps.
The embed iframe needs no API key, no billing account and no extension updates. For one office and one marker, it is genuinely hard to beat. Make it responsive with a small wrapper and one CSS rule in your template's custom stylesheet:
<div class="map-wrap">
<iframe src="https://www.google.com/maps/embed?pb=..."
loading="lazy" referrerpolicy="no-referrer-when-downgrade"
allowfullscreen></iframe>
</div>
/* custom CSS */
.map-wrap { position: relative; padding-bottom: 62%; }
.map-wrap iframe {
position: absolute; inset: 0;
width: 100%; height: 100%; border: 0;
}When a dedicated map module earns its keep
Map extensions from the Joomla Extensions Directory wrap the Google Maps JavaScript API in a module with admin-friendly options. They make sense when you need things the plain embed cannot do:
- Multiple markers with individual popup text — branch offices, dealers, event venues.
- Custom marker icons or map styling that matches your brand.
- Markers pulled from Joomla content, contacts or a third-party component.
- KML overlays, drawing shapes, clustering dozens of points.
The trade-offs are real, though. A dedicated module means one more extension to update, an API key to create and protect, and the full Google Maps JavaScript stack loading on your page. If your requirement is one pin on one map, a module is overkill; if it is a searchable dealer locator, a module (or a purpose-built component) is the sane choice.
API keys, and why so many old Joomla maps broke
If you have ever inherited a Joomla site with a grey box that says "This page can't load Google Maps correctly", here is the history. For years the Google Maps JavaScript API worked without any key. Then Google began requiring an API key for new implementations, and later tied all keyless usage to degraded, watermarked maps. Overnight, thousands of Joomla sites with older map extensions showed broken maps — nothing wrong with Joomla or the extension's code, just a missing key.
To get a working key you create a project in the Google Cloud console, enable the Maps JavaScript API (and the Embed or Static API if you use those), generate the key, and attach a billing account. Google gives a recurring monthly usage credit that comfortably covers a small site's traffic, but the billing account must exist. Then you paste the key into your map module's settings.
Two pieces of housekeeping matter here. First, restrict the key to your own domain in the console — an unrestricted key sits in your page source, and anyone can lift it and burn through usage on your account. Second, note that the simple Share-and-Embed iframe described earlier does not need any of this. When a client balks at creating a billing account, the keyless iframe embed is the escape hatch.
The performance cost nobody mentions
An interactive Google map is one of the heaviest things you can put on a page. The JavaScript API pulls in hundreds of kilobytes of script, plus tile images, fonts and tracking requests — often more than the rest of your page combined. On a slow phone connection, a map in the header can visibly delay everything else.
The fixes, in order of effort:
- Native lazy loading. Add loading="lazy" to an iframe embed. Browsers then defer loading the map until the visitor scrolls near it. One attribute, big win, no downsides for below-the-fold maps.
- Click-to-load facades. Show a static image of the map with a "View map" button; only inject the real iframe or script after the click. Some Joomla map extensions offer this as a "consent" or "lazy" mode.
- Put the map only where it belongs. A surprising number of sites load a map module site-wide because Menu Assignment was left on "all pages". Assign the module to the contact page only and every other page gets faster for free.
Test before and after with your browser's network panel. Watching a page drop by a megabyte because a map stopped loading on the homepage is a satisfying afternoon.
Privacy and consent: maps are third-party trackers
An embedded Google map sets cookies and sends the visitor's IP address and behaviour data to Google the moment the page loads, before the visitor has agreed to anything. Under GDPR and similar regimes, many site owners are advised to treat map embeds like any other third-party tracking and load them only after consent.
Practical patterns we use on European client sites:
- The click-to-load facade above doubles as a consent mechanism: the map loads only when the visitor asks for it, and you can put a one-line notice on the placeholder.
- Consent-management plugins for Joomla can block iframes and scripts by category until the visitor accepts, then release them.
- A static map image (next section) with a link out to Google Maps sends nothing to Google until the visitor deliberately clicks through.
We are webmasters, not lawyers — if your site operates where consent rules apply, get proper advice. But technically, the facade pattern satisfies the strictest reading and improves performance at the same time, so it is rarely the wrong choice.
Multiple markers, directions links and other upgrades
More than one location
The keyless iframe embed shows a single place. For several locations you have three options: create a custom map in Google My Maps (which supports many pins and layers, and gives its own embeddable iframe), use a map module that supports multiple markers through the JavaScript API, or — simplest of all — publish one small embed per location on a "Find us" page. My Maps is the underrated middle ground: no API key, no extension, decent editing interface.
Directions links beat embedded directions
Visitors on phones do not want directions inside your web page; they want them in their navigation app. A plain link does that perfectly:
<a href="https://www.google.com/maps/dir/?api=1&destination=Main+St+12,+Springfield">
Get directions
</a>On mobile devices this opens the Google Maps app with your address preloaded. Put it right under the map, style it as a button, and it will be used far more than any embedded widget. If you want that button to look the part, our walkthrough on how to create a call to action in Joomla applies directly.
Static maps: the fastest map is a picture
For a contact page whose only job is "show roughly where we are", consider skipping the live map entirely. A static map is a plain image of the map area with your marker on it. Google's Static Maps API generates them (key required), or you can take a screenshot of the map view you like and serve it as an optimized image — with attribution kept visible. Wrap the image in the directions link above and most visitors get everything they came for.
Here is how the approaches compare:
| Approach | API key needed | Page weight | Interactivity | Best for |
|---|---|---|---|---|
| Iframe embed in Custom HTML module | No | Medium to heavy | Pan, zoom, one marker | Single office contact pages |
| Dedicated map module (JS API) | Yes | Heavy | Full — markers, styling, clustering | Store locators, many markers |
| Google My Maps embed | No | Medium to heavy | Multiple pins, layers | A handful of locations, no budget |
| Static map image + link | Only if generated via API | Tiny | None on-page, full on click-through | Speed-critical and consent-sensitive sites |
Troubleshooting the classics
- Grey box or "for development purposes only" watermark: missing or unbilled API key. Fix the key and billing in the Google Cloud console.
- Map works on one domain but not another: the key's referrer restrictions do not include the second domain (www vs non-www catches people constantly).
- Iframe disappears after saving the module: the editor's HTML filtering stripped it. Switch the editor to None or adjust the text filter settings, then re-paste.
- Map tiles render half-grey in a tabbed or accordion layout: the map initialised while hidden. Look for a module option to refresh on show, or trigger a resize when the tab opens.
- Map shows the wrong place: re-copy the embed from Google Maps rather than editing coordinates in the URL by hand.
When an extension misbehaves beyond these, check its documentation and the official Joomla documentation before assuming the worst — nine times out of ten it is a key, a filter or an assignment setting.
FAQ
Do I need a Google API key to show a map on my Joomla site?
Not necessarily. The Share-and-Embed iframe from the Google Maps website works without any key or billing account, and so does a Google My Maps embed. You only need an API key when you use the Maps JavaScript API — which is what most dedicated Joomla map extensions do — or the Static and Embed APIs directly.
Why did the map on my old Joomla site suddenly stop working?
Almost certainly the API key requirement. Sites built before keys were mandatory kept working for a while under grandfathering, then broke or gained watermarks as Google tightened the policy. Create a key with billing enabled, paste it into the map extension's settings, and restrict the key to your domain. If the extension predates keys entirely and has no key field, replace it — or switch to the keyless iframe embed.
Does an embedded Google map hurt my page speed scores?
Yes, noticeably. The map's scripts and tiles often outweigh the rest of the page and drag down metrics like Total Blocking Time. Add loading="lazy" to iframe embeds, keep maps off pages that do not need them, and consider a click-to-load facade or static image when performance matters. A map at the bottom of a contact page with lazy loading is close to free; one in a site-wide header is not.
Can I show a map without sending visitor data to Google?
Only by not loading Google's resources until the visitor opts in. A static image hosted on your own server with a "Open in Google Maps" link sends nothing until the click. Click-to-load facades and consent managers achieve the same for interactive maps. Alternatively, self-hostable options built on OpenStreetMap data avoid Google entirely, at the cost of more setup work.
The bottom line
Match the tool to the job. One location: keyless iframe embed in a Custom HTML module, lazy-loaded, with a directions link underneath. A handful of locations: Google My Maps. A real locator with custom markers and search: a dedicated map module with a properly restricted API key. And when speed or privacy tops the list, a static image linking out to Google Maps quietly outperforms them all. Whichever route you take, keep the map only on the pages that need it — your other pages will thank you. More practical guides live in our Joomla hub.