Why I ship vector tiles instead of an iframe
The first map I ever put on a client site was an iframe. I copied it out of Google Maps, pasted it into the page, and it worked on the first try. Then I spent an hour trying to make it stop looking like a Google map, and I could not, because there was nothing in there to change.
That hour is where this plugin comes from. Everything technical I have chosen since follows from one observation I did not have the words for at the time.
Two things up front, since both get their own section later. For a lot of sites the iframe is still the right answer. And my map needs WebGL, so a visitor whose browser does not have it gets nothing, not even a static image.
An iframe embeds a map I do not style directly
When you embed a Google map in an iframe, you are embedding another document on your page. That document can contain an interactive map, but its internal styling is controlled by the embedded service. The road colors, the type, the water, the controls in the corner: all of it arrives finished.
You can move the window. You can size it, round its corners, give it a border. You cannot repaint what is behind it. Your CSS stops at the frame, because the browser will not let one site reach into another site’s document, and it is right not to. My page can style the frame, but it cannot directly restyle Google’s cross-origin map document.
I have written about the other half of that arrangement, which is what you have to sign up for before the window appears. This post is about the rendering, not the paperwork.
What a vector tile actually is
Modern Maps applies its map style through a renderer on the page.
A vector tile is a small package of geometry and categories. This line is a road of kind minor. This polygon is water. This point is a place with a name. There are no colors in it, no fonts, no decisions. It is a description of what is there, and nothing about how it should look.
The drawing happens in the visitor’s browser, from a style: a list of rules that match those categories to paint. Named once, without ceremony, the stack is MapLibre GL JS as the renderer, basemap data from Protomaps built on OpenStreetMap, delivered as PMTiles from tiles.modernmapswp.com. Label text is drawn from font files served as glyphs from protomaps.github.io. None of it goes to Google.
Here is the entire rule for water in the dark style, copied out of the source:
{
id: 'water',
type: 'fill',
source: 'protomaps',
'source-layer': 'water',
filter: ['==', '$type', 'Polygon'],
paint: {
'fill-antialias': false,
'fill-color': COLOR_WATER,
},
}
That is not a description of the water on the map. It is the instruction that makes water appear at all. Change what COLOR_WATER resolves to and every lake, river, and bay in the world changes with it, in the browser, while the visitor is looking at it.
An iframe embeds a map document. Modern Maps exposes the style rules for the map on your page.
Who controls the map’s styling?
Compare the controls available in an embed with those in Modern Maps.
| Google Maps embed | Modern Maps | |
|---|---|---|
| What the page includes | Google’s interactive map document in an iframe | A map renderer and separately loaded map assets |
| Where rendering happens | Inside the embedded document; an iframe does not specify its renderer | MapLibre GL JS in the visitor’s browser |
| Styling controls | The options supported by the chosen embed | The controls exposed by Modern Maps |
| Labels | Controlled by the embedded map | Styled and placed by the map renderer |
| Google-specific features | Depend on the selected embed mode | Not included |
| Loaded from | google.com | tiles.modernmapswp.com, protomaps.github.io |
Why this made styling possible
This is the part I actually cared about, and it is the reason the hosting bill is worth paying.
You can put a CSS filter on an iframe element. It works, in the sense that the pixels change. It also moves the labels, the logo, and the little yellow figure in the corner, because a filter has no idea which pixels are which. Everything shifts together, by the same amount, in the same direction. That is the difference between a map that has your colors and a map that has been tinted.
With access to the renderer’s style rules, water and roads and building fills and label halos are separate things I can style by name. Darkening the land does not smear the type. Warming the roads does not touch the water. The map can be quiet where the page is quiet and sharp where the page is sharp, because each of those is a decision somebody made on purpose rather than a side effect of a filter.
The proof is easier to look at than to describe. There are two dozen examples in the gallery, all of them the same data drawn different ways. Midnight is the one for when the map should sit down and be quiet.
Control over label styling
A second thing falls out of this, and I did not expect to care about it as much as I do.
Labels are their own layer, matched to a font file rather than baked into an image, and placed by the renderer as the map moves. Street names bend along the street. Text stays crisp when you zoom, because it is being set fresh rather than scaled up out of an image. And when two labels want the same patch of screen, the renderer knows about both and can drop one instead of printing them on top of each other.
Modern Maps exposes the style rules used by its renderer. An iframe can also contain a browser-rendered map; the difference here is which controls the site owner can use.
What it costs
Here is the honest part, and I am not going to bury it under the good news.
The map needs WebGL, and right now there is no fallback. If a visitor’s browser has WebGL disabled, unavailable, or blocked (a hardened privacy setup, an old device, certain locked-down configurations), they do not get a degraded map. They get an empty box. No message, no static image, nothing. In the source that gap is a TODO next to the line that creates the map, which is exactly as much as I can honestly claim about it. A fallback is the obvious fix. I am not going to name a version or a date for it here.
It also means the map needs the network. Tiles are fetched while the page loads. This is not a map that works on a plane.
Where the iframe still wins
I want to be straight about this, because a post like this one is worthless if it only argues one way.
An iframe has nothing to install. No WordPress map plugin to install or maintain, and no code of mine between you and the embedded map. You copy it from Google and paste it into the page and you are finished, and that is a real advantage that no amount of styling control cancels out.
Google offers place, directions, search, and Street View modes through its Maps Embed API. Check the mode and features of the embed you choose. I do not have any of that, and I am not going to. If what you need is “show people where we are and let them tap for directions,” the iframe is a good answer, and for plenty of sites it is the correct one.
If you want that question answered as a buying decision instead of a rendering one, I laid out every option side by side in how to add a map in WordPress.
What I was actually after
The reason to take on hosting a basemap was not speed and it was not principle. It was that hour with the client site, when I realized the map was the only element on the page I was not allowed to design.
I wanted the map to be part of the page rather than a hole in it. Vector tiles gave me that control, and everything else in this post follows from that choice.
If you want to see what that looks like on a page of your own, the plugin is here.