Maps

The Map block shows a live map with as many markers as you like: your shop, a venue, the places a tour visits. It needs no code and no account. By default it draws with the free map pictures from OpenStreetMap.

After this chapter you can add a map and its markers, change how the markers look, pick a map style, and decide when a map loads.

Add a map and its markers

  1. In the page editor, open the Blocks list and drag Map, in the Elements group, onto the page.
  2. Open the block's Markers and add a row for each place.
  3. For each marker, set its Place. Click the small map to drop the point and drag it to adjust. Or type a Latitude and Longitude, which are the place's coordinates in degrees. Or type a name or address into Find a place and press Enter. A row with no place is left off the map.
  4. Fill in the marker's Title, Popup text, Link and Link text. They show in a popup when a visitor presses the marker, or tabs to it and presses Enter. The text is plain text and line breaks are kept.
  5. Set Open popup when the map loads to Yes on one marker if you want the map to start with its popup showing.
  6. Press Save draft and check the preview.

By default the map frames every marker (View is Fit all markers), and it never zooms in closer than Closest zoom when fitting, so a single marker does not land at street level. To choose the view yourself, set View to Set by hand, pan and zoom the small map, and press Use this view.

Change how the markers look

The Marker field of each marker is Icon or Image. The fields below carry a note of which kind of marker uses them, because one map can mix both.

  • Icon draws a symbol. Pick it under Icon (icon markers), from the same library as the Icon block, including brand marks such as brand:instagram. Shape (icon markers) is Pin, Circle or Icon only. Colour (icon markers) is the fill of the pin or circle, or the icon itself for Icon only. Icon colour (pins and circles) is the symbol on a pin or circle.
  • Image uses a picture from the media library, chosen under Image (image markers), such as your logo. Size in px (image markers) sets its width and the height follows the picture. Image point (image markers) says which point of the picture sits on the place: the Bottom, as for a pin, or the Centre, as for a round logo. Give the marker a Title so the picture is announced to a screen reader.

Marker colours come from your theme, so they match the rest of the site and follow it when it changes. To use a colour the theme does not have, open Settings → Theme, add the colour under Colours with a name such as venue, and save. It then appears in the marker colour lists (Theme).

Size, moving and the list of places

  • Height is Small, Medium, Large or Extra large, and can differ by screen size. Corners and Padding do what they do on other blocks.
  • Moving the map is Drag and zoom, Zoom buttons only or Still map. On a phone with Drag and zoom, one finger scrolls the page and two fingers move the map. A short hint says so, and you can reword it in Two-finger hint.
  • The scroll wheel zooms the map only if you set Zoom with the scroll wheel to Yes, so scrolling past a map never gets caught by it.
  • List of places can show every marker's title, text and link under the map. Left on Screen readers only, the list is still there for screen readers and hidden from everyone else.
  • Map name (read aloud) is what a screen reader calls the map.

Map styles

A map is made of small pictures called tiles, which come from a map service. Every site has OpenStreetMap built in. The block's Map style field picks the style, and lists any others the site has added.

The OpenStreetMap usage policy

OpenStreetMap's tile servers are free and run by volunteers, and they come with a policy. A small site's map is fine. The attribution on the map must stay, and the block always shows it. Heavy use is not allowed. A busy site, a page with many maps, or a map that many visitors open should use a provider that sells tiles for that. The policy can change, so read it at operations.osmfoundation.org/policies/tiles before you rely on it.

Add a provider with a key

Providers such as MapTiler, Stadia Maps and Thunderforest give you a key. A developer adds the provider to the site in four steps. The example uses MapTiler.

  1. Add the key to the site's .env file. Replace the value with your own key.
.env
CMS_MAPS_MAPTILER_KEY=your-maptiler-key
  1. Add the provider to site.config.ts, as the maps entry inside defineConfig. Write {key} where the provider's address wants the key, and use the provider's own wording for the attribution.
site.config.ts
maps: {
  styles: [
    {
      id: 'light',
      label: 'Light',
      url: 'https://api.maptiler.com/maps/dataviz/{z}/{x}/{y}.png?key={key}',
      key: process.env.CMS_MAPS_MAPTILER_KEY,
      attribution: '© MapTiler © OpenStreetMap contributors',
      maxZoom: 20,
    },
  ],
},
  1. Restart the site. The style, called Light here, now appears in every Map block's Map style list.
  2. Restrict the key to your site's domain in the provider's dashboard. A tile key is public by nature, because the visitor's browser sends it to the provider with every tile. Restricting it stops anyone else spending your allowance.

The attribution is always shown on the map, as every provider requires. Once a keyed style is set up, add osm: false to maps to remove OpenStreetMap from the list. Maps that used it switch to your first style.

Privacy and “Load the map”

Each tile request tells the tile service the visitor's address. By default the map loads as it scrolls near the screen. If your site asks visitors for consent first, or you would rather not share addresses until someone asks for the map, set Load the map to “When a visitor asks (no tiles load before)”.

The map then shows a button, labelled Load button text and “Show map” by default, with a Note under the button. Nothing reaches the tile service until the visitor presses the button. Use the note to say whose servers the tiles come from, for example “Loads map tiles from OpenStreetMap.” The choice is not remembered between pages.

If your site sets a Content-Security-Policy

A Content-Security-Policy is a header that tells browsers which addresses a page may load things from. A new site's Caddyfile does not set one. If yours, or a proxy in front of it, does, the tile host must be allowed in img-src, or the map shows grey squares. For OpenStreetMap that is https://tile.openstreetmap.org. For a keyed provider, use its tile host, such as https://api.maptiler.com.

Place search

Find a place in the marker editor uses OpenStreetMap's Nominatim service, called from your site's server. It makes one search each time you press Enter and no more than one a second, and it keeps results for a day. It is meant for light editing use. To turn it off, add geocoder: false under maps in site.config.ts. The search box then goes away, and you place markers by clicking the map or typing coordinates.