Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.

<mapml-viewer> custom element

Build Status Continuous Testing

The <mapml-viewer> custom element is a prototype implementation of the <map> media element defined in the MapML (Map Markup Language) specification.


Beginning with v0.8.2, <mapml-viewer> can be loaded from the UNPKG content delivery network

<script type="module" src=""></script>

– or installed using npm.

npm install @maps4html/web-map-custom-element

Note: v0.8.X npm releases are functionally equivalent to standalone releasev0.8.0.


The HTML author can add MapML sources (layers) by specifying one or more <layer-> custom elements as children of <mapml-viewer>.

The map provides a default set of controls which are turned on or off with the map's controls boolean attribute.

The initial zoom and location of the map are controlled by the zoom, lat and lon attributes. The default projection is OSMTILE (Web Mercator).

Example markup of a basic map

<mapml-viewer zoom="3" lat="0" lon="0" controls>
  <layer- src="" label="OpenStreetMap" checked></layer->

Styling the map element

It is recommended to use the :defined pseudo-class to progressively style the map element. It ensures styles only apply in browsers that support custom elements.

mapml-viewer:defined {
  background-color: black; /* custom background color */
  border: none; /* remove default border */
  max-width: 100%; /* responsive map */

A parallel customized built-in element

The <map is="web-map"> customized built-in element is developed in parallel to the <mapml-viewer> autonomous custom element. Please note that <map> as a customized built-in element has proven to have a critical accessibility issue in some browsers, which causes screen readers not to announce any of the map element's content, it is therefore recommended not to use <map is="web-map"> in production.

Maps for HTML Community Group

MapML and the custom map elements are being developed by the W3C Maps for HTML Community Group. Membership in the group is encouraged, however you do not have to join to use the information found here. If you wish to contribute, please join the Maps For HTML Community Group, and help us make the Web a map-friendly platform for everyone, everywhere!