Appearance
Maps
Leaflet for interactive maps — self-hostable, tile-agnostic, and no API key.
Why not Google Maps or Mapbox
| Issue | Consequence |
|---|---|
| Mandatory API key | Every deployment needs credential provisioning |
| Usage billing | A public dashboard can generate an unexpected invoice |
| Third-party origin | Violates the no-CDN policy and most strict CSPs |
| Data transmission | Sends user IPs and viewport data to a third party — a GDPR consideration |
| Terms of service | Restrictions 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="© 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-attributionand 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
| Attribute | Default |
|---|---|
data-av-map-center | [53.3498, -6.2603] (JSON) |
data-av-map-zoom | 12 |
data-av-map-tiles | none — no tiles are drawn |
data-av-map-attribution | empty |
data-av-map-max-zoom | 19 |
data-av-map-markers | [] (JSON) |
data-av-map-scroll-wheel-zoom | false |
--av-map-height (CSS) | — |
Events
| Event | Detail |
|---|---|
av:map:ready | { el, instance } |
Checklist
- [ ] A text equivalent exists (
<noscript>list, table, oraria-labelwith 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.