Skip to content

Maps ​

Leaflet for interactive maps — self-hostable, tile-agnostic, and no API key.


Why not Google Maps or Mapbox ​

IssueConsequence
Mandatory API keyEvery deployment needs credential provisioning
Usage billingA public dashboard can generate an unexpected invoice
Third-party originViolates the no-CDN policy and most strict CSPs
Data transmissionSends user IPs and viewport data to a third party — a GDPR consideration
Terms of serviceRestrictions on caching, screenshotting, and redistribution

Leaflet is BSD-2, tile-agnostic, and can point at your own tile server.


Leaflet ​

BSD-2 · lazy — downloaded only on a page that has a [data-av-map].

html
<div class="av-map"
     data-av-map
     data-av-map-center="[53.3498, -6.2603]"
     data-av-map-zoom="12"
     data-av-map-tiles="/tiles/{z}/{x}/{y}.png"
     data-av-map-attribution="&copy; OpenStreetMap contributors"
     data-av-map-markers='[
       { "at": [53.3498, -6.2603], "label": "Dublin warehouse — 12 Dame Street" },
       { "at": [53.3382, -6.2591], "label": "Portobello depot — 4 Grove Road" }
     ]'
     style="--av-map-height: 340px"
     role="application"
     aria-label="Map of delivery locations">
  <noscript>
    <ul>
      <li>Dublin warehouse — 12 Dame Street</li>
      <li>Portobello depot — 4 Grove Road</li>
    </ul>
  </noscript>
</div>

The <noscript> list is not decoration — it is the accessible equivalent, and it is what a screen reader user, a search engine and a printed page get.

No default tile provider ​

data-av-map-tiles has no fallback. A default would make every map issue requests to a third-party origin, which is what the no-CDN position exists to prevent, and it concerns your users' IP addresses and your CSP — not a decision to make on your behalf. A map without tiles still pans, zooms and shows its markers. tests/map.mjs asserts the page makes no off-origin request.

Important — tile requests are third-party requests unless you host the tiles. TileServer GL plus an OSM extract for your region typically fits in a few GB. Attribution is a licence requirement for OSM data; set data-av-map-attribution and do not remove the attribution control.

Markers ​

Markers come from data-av-map-markers, a JSON array of { at: [lat, lng], label }. Each is a divIcon styled from tokens, so it follows the preset; a label becomes the marker's title and its popup. There is no clustering. src/scss/plugins/_leaflet.scss themes popups, zoom controls and attribution from tokens.

Scroll-wheel zoom ​

Off unless data-av-map-scroll-wheel-zoom="true". A map that captures the wheel traps the page: someone scrolling past a full-width map should not find themselves zoomed into a street.

Reaching Leaflet ​

av:map:ready hands over { el, instance }, where instance is the Leaflet map — add layers, fit bounds or bind your own events there. AdminVora.destroy(root) calls map.remove().


Geocoding ​

No geocoder is bundled — every provider needs an API key and has different terms.

js
// Nominatim (OSM) — free, but rate-limited to 1 req/sec and requires a User-Agent
async function geocode(query) {
  const res = await fetch(
    `https://nominatim.openstreetmap.org/search?format=json&limit=1&q=${encodeURIComponent(query)}`,
    { headers: { 'Accept-Language': document.documentElement.lang } });
  const [first] = await res.json();
  return first ? [Number(first.lat), Number(first.lon)] : null;
}

Warning — geocoding from the browser exposes your users' searches to the provider and will get you rate-limited or blocked. Proxy it through your backend, cache aggressively, and store coordinates on the record rather than geocoding on every render.


Static map fallback ​

For emails, PDFs, print, and no-JS contexts:

html
<picture>
  <source srcset="/api/static-map?lat=53.3498&lng=-6.2603&zoom=13&w=800&h=400&theme=dark"
          media="(prefers-color-scheme: dark)">
  <img src="/api/static-map?lat=53.3498&lng=-6.2603&zoom=13&w=800&h=400"
       alt="Map showing 12 Dame Street, Dublin 2"
       width="800" height="400" loading="lazy">
</picture>
scss
@media print {
  .av-map { display: none; }
  .av-map-static { display: block; }
}

Attributes ​

AttributeDefault
data-av-map-center[53.3498, -6.2603] (JSON)
data-av-map-zoom12
data-av-map-tilesnone — no tiles are drawn
data-av-map-attributionempty
data-av-map-max-zoom19
data-av-map-markers[] (JSON)
data-av-map-scroll-wheel-zoomfalse
--av-map-height (CSS)—

Events ​

EventDetail
av:map:ready{ el, instance }

Checklist ​

  • [ ] A text equivalent exists (<noscript> list, table, or aria-label with the data)
  • [ ] Every marker has a label
  • [ ] Scroll-wheel zoom left off unless the map is the page
  • [ ] Attribution control present and not removed
  • [ ] Tile provider is self-hosted where CSP or privacy requires it
  • [ ] Geocoding proxied through the backend and cached
  • [ ] Static image fallback for print and email
  • [ ] AdminVora.destroy(el) called before a framework removes the map
  • [ ] Consider whether a table or bar chart would answer the question better

Read next: Dashboards.

Documentation for @creativeigniter/adminvora