@mmj-map/elements
v0.13.0
Published
Self-hosted web map as Web Components: a real map on a page with plain HTML. No API key, no per-view billing, no tile server, no build step. Works offline.
Maintainers
Readme
@mmj-map/elements
Web Components that put a real map on a page with plain HTML. Self-hosted: you serve the tiles, so there is no API key, no per-view billing, no tile server and no build step — and the map keeps working with no network.
日本語版は README.ja.md にあります(こちらが詳しい版です)。
| | |
|---|---|
|
Directions with the buildings up. Turn-by-turn callouts, and a photo at the corner where you turn. |
Time-stepped overlays. Rain radar, storm and gale areas, a forecast cone — twelve hours from PNG files. |
Everything you see there is static files on GitHub Pages. There is no backend behind any of it.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/maplibre-gl.css">
<style>mmj-map { display: block; height: 70vh; }</style>
<mmj-map
tiles="./tiles/japan.pmtiles"
style-url="./styles/modern-dark.json"
center="135.5023,34.6937"
zoom="12">
<mmj-marker lnglat="135.4959,34.7024" popup="Umeda"></mmj-marker>
</mmj-map>
<script type="module">
import * as maplibregl from "https://cdn.jsdelivr.net/npm/[email protected]/dist/maplibre-gl.mjs";
window.maplibregl = maplibregl;
</script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/pmtiles.js"></script>
<script type="module" src="./elements/index.js"></script>center is longitude,latitude — the same order as GeoJSON, not the order you say out loud.
When this is the right tool
A self-hosted alternative to a keyed map API, built on MapLibre GL JS and PMTiles.
- "Our map bill grows with traffic we do not control." There is no meter. You cut the area you need once and serve it as a file, so traffic costs what your static host charges for a file — which for most sites is nothing.
- "The venue has no signal." A hall, a basement, a festival site, a drill. The tiles are files you ship, and GPS comes from satellites, so the map and the blue dot both still work offline.
- "We cannot send our users' whereabouts to a third party." Nothing leaves your origin. No account to register, no request to anyone else's API.
- "We just need a map inside a page we already have." A handful of HTML attributes. No bundler, no framework, no build step — the package ships plain ESM.
You host the data. This package only draws it.
tiles and style-url point at files you put somewhere. There is no delivery origin
behind this package, which is why there is no key and no metered billing. A single
PMTiles archive on static hosting is enough —
the browser fetches byte ranges out of it over HTTP.
Need an archive? @mmj-map/tiles cuts one
for any bounding box on earth from public data, with no account:
npx @mmj-map/tiles extract osaka --bbox=135.4,34.6,135.6,34.8Elements
| Element | What it does |
| --- | --- |
| <mmj-map> | The map itself. Themes, 3D buildings, geolocation, URL hash, fullscreen |
| <mmj-marker> | One point with an optional popup. draggable lets people move it to the right spot (finger, mouse or arrow keys), within drag-radius metres |
| <mmj-poi> | Your own GeoJSON points, with optional rich cards and a linked list |
| <mmj-cluster> | Many points, grouped as you zoom out. weight-key sums counts (e.g. shops per station); mmj-visible and select(id) keep your own list in step with the map |
| <mmj-route> | A path with step-by-step callouts (it does not compute routes) |
| <mmj-circle> | A radius in real metres from a point. blur and label show a rough area ("around the station") instead of an exact spot |
| <mmj-raster> | A raster overlay — rainfall, hazard maps, aerial imagery |
| <mmj-fill> | Polygons shaded by a value — flood depth, ground type, intensity — or named areas in one colour, with an edge that fades outward (blur, ground metres) and a name label (label-key) |
Every element is plain ESM. There is nothing to compile; copy src/ if you prefer.
Coastlines and prefecture borders, without a map
Drawing your own SVG figure (a typhoon track chart, say) and only need the coast and the prefecture lines underneath? Pull them out of the same Protomaps tiles. No new data and no server: PMTiles over HTTP Range, in the browser or in Node.
import { PMTiles } from "pmtiles";
import { extractOutline, svgHeight, toSvgPath } from "@mmj-map/elements/outline";
const bbox = [128, 30, 146, 46]; // [west, south, east, north]
const outline = await extractOutline({ source: new PMTiles(url), bbox, zoom: 5 });
const height = svgHeight(bbox, 600);
const coast = toSvgPath(outline.features.filter((f) => f.properties.kind === "coastline"), { bbox, width: 600, height });Fill land, stroke coastline / region / country with stroke-linecap="round", and show outline.attribution (© OpenStreetMap contributors) on the figure.
The pin, without the elements
Already drawing your own map with maplibre-gl? Borrow the slanted pin used by <mmj-cluster pin="machibari"> without placing any element:
import { needleImage, needleLayout } from "@mmj-map/elements/machibari";
for (const picked of [false, true]) {
const pin = needleImage({ color: "#e4572e", picked });
if (pin) map.addImage(picked ? "pin-picked" : "pin", pin.image, { pixelRatio: pin.pixelRatio });
}
map.addLayer({
id: "shops",
type: "symbol",
source: "shops",
layout: { "icon-image": "pin", ...needleLayout() },
});needleLayout() is what puts the tip of the needle on the coordinate. Without it, the centre of the picture lands there and the pin points somewhere else.
Cards, without writing a UI
<mmj-poi> can build a card from your GeoJSON properties: photos, rating, tabs, opening
hours per weekday, labelled links. The open item is kept in ?shop=, so a single place
can be shared as a link.
<mmj-poi src="./data/shops.geojson"
card-title="shop_name" card-images="photos" card-body="description"
card-tabs="Menu:menu,Coupon:coupon,Hours:hours"></mmj-poi>card-live re-fetches the parts that change over time when the card opens.
card-rich lets named fields contain HTML — off by default, and only the fields you name.
Requirements
| | |
| --- | --- |
| MapLibre GL JS | >=5 (peer dependency, optional) |
| pmtiles | >=4 (peer dependency, optional) |
| Browser | WebGL2 is required by MapLibre 6 |
MapLibre 6 ships ESM only. dist/maplibre-gl.js (the UMD build) no longer exists, so
changing only the version number in an old <script src=...> line gives you a 404 and a
blank map. Use the <script type="module"> form above, and take the namespace with
import * as — v6 has no default export, so a default import silently yields undefined.
Attribution is not optional
The base data is OpenStreetMap under ODbL. The elements render
© OpenStreetMap contributors and the attribution control cannot be removed.
Keep it visible. See LICENSES.md.
Where to find things
| You want | Go to |
| --- | --- |
| Every attribute, in one fetch | https://meta-taro.github.io/mmj-map/llms-full.txt |
| An index plus a copy-paste starter | https://meta-taro.github.io/mmj-map/llms.txt |
| The same, offline | node_modules/@mmj-map/elements/llms.txt |
| What changed between versions | CHANGELOG.md |
| Live examples of all of it | https://meta-taro.github.io/mmj-map/ |
| The detailed Japanese docs | README.ja.md |
If you are handing this to an agent, hand it llms-full.txt rather than this page.
License
MIT for the code. Map data is OpenStreetMap, ODbL — see the attribution section above.

