HTML5/JavaScript maps by

This weekend, I got the chance to play around with HTML5 maps by Here are the stuff you need to know to set up HTML5 maps on your website and my thoughts on the same.

About the Maps

The current version of HTML5 maps by (at the time of writing this article) is v1.2 and currently they provide a complete World Map, a US Map and a map of Canada.
Each of these maps are sold separately with their own single-domain licenses. Fortunately they also provide a free trial version of each map that you can check out before buying, though it comes with a huge TRIAL watermark and some limited functionality.
The maps are created using Raphael.js. The World map is in the Robinson projection while the US map uses the more common Lambert projection.

World Map using Simplemaps

World Map

The HTML5 world map comes with 176 countries. The map is initially zoomed out and the whole map is divided into sub-regions which are by default: North America, South America, Africa and Middle East, Europe, North Asia and South Asia.
Clicking on a region zooms in on the particular region and country-level interaction is then possible.
Hovering over a country displays a tooltip which by default contains the country name and a blank field which can be set to display HTML/CSS content using the country_specific setting variable.
A very handy feature of this map is the possibility to assign a specific URL to each country so that when the user clicks on it, he/she will be taken to that URL.

The US Map

The HTML5 US map is very similar to the world map in most aspects.
The US map displays all the states of USA with each of them being interactive by default.
This map uses the Lambert projection and displays 2-letter codes as labels for each state on the map.
Most of the setting variables are common to both the World and US versions.
In the US map, there are 2 extra setting variables in the main_settings variables called 'label_color' and 'hide_labels'

Setting up the maps

What struck me in particular about this script is the easy installation process. Almost no advanced knowledge of HTML or JavaScript is required to successfully setup the script.
Moreover it comes with a usage example and pdf documentation that is easy to follow.
The maps consist of basically two JavaScript files:
mapdata.js — This file contains all the configuration information and should be included before any other file.
worldmap.js OR usmap.js — This file contains the code for rendering the map, the interactivity and path information. This script is compressed and obfuscated so if you don’t have enough knowledge, you must not try editing it.
The simplest way to get the map up and running is to directly edit the example file or create a new HTML file with the following code:

<!DOCTYPE html>
<html lang="en">
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <title>HTML5/Javascript World Map</title>
		<script type="text/javascript" src="path/to/mapdata.js"></script>	
		<script  type="text/javascript" src="path/to/worldmap.js"></script>
		<h1>HTML5/Javascript World Map</h1>
			<div id="map">
			<p>Please read the <a href="Documentation.pdf">documentation</a> to learn how to customize this map.</p>

Here you must appropriately enter the relative path of scripts.

The map is rendered in a div with id map when the page finishes loading.

Configuring the map

There are dozens of options that you can set to customize the map.
Every configuration option can be set in the mapdata.js file.
Basically there are 3 global setting parameters that need to be set, they are: main_settings, country_specific OR state_specific, and locations.
Each of these are object variables with several properties. Lets look at each of them in brief:

  1. main_settings :
    This setting object contains the following properties, which are very self-explanatory:

    • width: (number) The width of map in pixels, height is calculated automatically
    • background_color: (string) A HEX color value specifying the background color to use for maps
    • background_transparent: (string) ‘yes’ or ‘no’
    • border_color: (string) The color to use for borders of the map
    • pop_ups: (string) ‘click’, ‘hover’ or ‘detect’
    • country_description: (string) The description to show in tooltips on a country if country_specific description is not provided
    • country_color: (string) The color to assign to countries
    • country_hover_color: (string) The color for countries on hover
    • country_url: (string) The url to navigate to when a user clicks on a country, if no country_specific url is provided
    • all_countries_inactive: (string) ‘yes’ or ‘no'; whether to disable interactivity at country level
    • location_description
    • location_color
    • location_url
    • location_size: (number) The size of the square location marker, by default 25
    • all_locations_inactive
  2. country_specific:
    This is an object containing country-level details for all countries on the map.
    It consists of objects representing each country by their 2-letter ISO code which in turn contain several configurable properties.
    For example, the settings for USA look like this:
        US: {
            name: 'United States of America',
            description : 'This will show-up on hovering over US, and can contain rich media',
            color: '#ff9900', // each country can be assigned a unique color with this parameter
            hover_color: '#0099ff',
            url : '', // the url to navigate to when US is clicked on map
        . // 175 other countries

    By default, the mapdata.js file contains default values for all countries, to change a value, you can either edit them in-place or write your own settings at the end of mapdata.js, which will override the default values.

  3. location_specific:
    The script also allows to mark specific locations by defining their geographical latitude and longitude.
    This setting variable is an array of objects with each object representing a geographical location to mark on the map.
    For example; to mark Disney Land on the map you can write:
    var locations = [
    		name: "Disney Land",
    		lat: 33.8090, 
    		lng: -117.9200,
    		description: 'default',
    		color: 'default',
    		url: 'default',
    		size: 'default' 

    color in the context of location_specific defines the color to use for the square markers, the other properties have same meaning as in country_specific

The US map has similar configuration options, with the difference being that instead of country_specific, the us map has the state_specific setting variable with similar properties.

What can you do using these maps?

These maps are best suited to display geographical/statistical data and can be used by academia, and universities as an aid in teaching.
These can be used to create weather maps of the world/US, or any other geographical information, the possibilities are only limited by your access to data and imagination.
For example, I have created a simple world map that displays a countries’ capital, tld, telephone prefix, and timezone offset from GMT on hovering over it. You can check it out here. The data was downloaded from in JSON format.


The good

  • Extremely simple to set up and configure, no advanced technical know-how required
  • Fully compatible with most modern mobile browsers (iPhone and iPad included) and degrades gracefully to support non standard-compliant browsers
  • Robinson projection for World map which is aesthetically pleasing

The not so good

  • The world map script is very large (400+kb) and may load very slowly on slower connections and may also deplete your bandwidth quickly
  • Performance issues on the world map, zooming transitions not being very smooth
  • The classic tooltip flickering issue, when the mouse cursor moves over the tooltip area


If you are looking for a map with ease of use and maintenance being at high priority, then I would thoroughly recommend this map to you. For developers, its extremely easy setup process can mean that your client can himself edit and customize this map without having to call you each time he wants a color changed or a country information modified.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

2020 All rights reserved | Powered by WordPress
Back to top
Theme by