EtchMap

GitHub | NPM | API Doc

A browser library for smooth interactive XYZ raster-tile maps like OpenStreetMap.

• Canvas-based.
• Minimal by design: only renders the map and handles the usual pan and zoom interactions.
• Developer-friendly onDraw callback to draw application-specific visuals after the map has been rendered in each frame.
• Programmatic usage through the MapComponent class.
• Declarative usage through the <kayahr-map> custom element.
• Configurable map source. Defaults to OpenStreetMap.
• Built-in Web Mercator and linear projections with support for custom projections.
• Zero runtime dependencies.

Declarative creation

Import the package module, give the element a CSS size, and specify the initial view directly in HTML.

<script type="module">
  import "@kayahr/etchmap";
</script>

<style>
  kayahr-map {
    width: 100vw;
    height: 100vh;
  }
</style>

<kayahr-map center-x="6.9603" center-y="50.9375" zoom="13"></kayahr-map>

JavaScript can access the complete component API of a declaratively created map with document.querySelector("kayahr-map").getComponent().

Programmatic creation

import { MapComponent } from "@kayahr/etchmap";

const map = new MapComponent({
    center: { x: 6.9603, y: 50.9375 },
    zoom: 13
});

map.onDraw = (context, map) => {
    const point = map.projectPoint({ x: 6.9583, y: 50.9413 });
    context.fillRect(point.x - 4, point.y - 4, 8, 8);
};

document.body.append(map.getElement());

Demos

• Simple demo (Source) - Uses the default OpenStreetMap source and the onDraw callback to position an HTML marker at Cologne Cathedral.
• GW2 demo (Source) - Renders the Tyria world map from the Guild Wars 2 map API as a linear tile source with viewport covering disabled.
• Flights demo (Source) - A more complex animated example with moving aircraft, dynamically changing routes and naturally projected great-circle polylines.

See also

• View options
• onDraw callback
• Map input events
• Tile sources and projections