Show Nav

JavaScript Maps

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Overview

JavaScript maps allow you to convey information by geography about people, the economy, migrations, elections, trade and more. ZingChart offers almost 200 predefined maps types, as well as the option to pass outside GeoJSON files to create your own custom maps shapes. Browse the ZingChart Gallery for more examples.

Load Maps Modules

In addition to the core library, the maps modules must be explicitly loaded in order to render your map(s). Make sure to include the main maps module, as well as each map by module name, e.g., maps-world-continents.

zingchart.loadModules('maps, maps-world-continents', function(e) {
  zingchart.render ({
    id: 'myChart',
    data: {
      ... //Use the chart object to configure your map.
    },
    height: 400,
    width: '100%'
  });
});

Refer to the Maps List for a full list of available maps by module name.

Maps Type and Name

ZingChart maps are comprised of ZingChart shapes. In the chart object, create a shapes array of objects. In the object, add a type property and set the value to 'zingchart.maps'. Next, create an options object. Add a name property, and set the map name, e.g., world.continents.

Refer to the Maps List for a full list of available maps by map name.

Options Configuration

Use the options object to configure the map and its items (countries in a world map, states in a country map, counties in a state map, and so on) with the following properties.

Include

Use the items array to include only the specified items in your map. Provide the items to include as string values separated by commas inside an array. (Note the exception for the world countries map below.)

Note: Use the getItems() method to reference the item names of a particular map.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

World Countries Only: In lieu of the items array, use the groups array to include only the specified items in your map.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Ignore

Use the ignore array to ignore the specified items in your map. Provide the items to ignore as string values separated by commas inside an array.

Note: Use the getItems() method to reference the item names of a particular map.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Bounding Box

Use the bbox array to overlay maps on top of other maps. Provide the coordinates as number values separated by commas inside an array.

Note: Use the getItemInfo() method to obtain the bbox coordinates of a particular map item.

Note: As of Build 2.6.0, this property does not work unless zooming, panning, and scrolling are disabled.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Scale

By default, map scaling, where the normal aspect of the map is preserved, is automatically enabled. Use the scale property to enable (true) or disable (false) this setting.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Zoom

Use the zoom property to set the zoom level of the map at chart render. Provide an integer value.

Note: Use the offsetX and offsetY properties to adjust the positioning.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Zooming, Panning, Scrolling

By default, map zooming, panning, and scrolling are automatically enabled. Use the zooming, panning and scrolling properties to enable (true) or disable (false) these settings.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

To style the zoom controls, use the controls object. Use the placement property to place the zoom controls at the top-left ('tl'), top-right ('tr'), bottom-left ('bl'), or bottom-right ('br') corner of the map.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Tokens

Maps use the following tokens:

Token Description
%data-_____ Format for custom tokens. Use the data- prefix to define the name, e.g., 'data-region', and the the %data- prefix to return the value, e.g., %data-region.
%long-text
%text
The full name of the map item.
%short-text The abbreviated name of the map item.

Refer to the Tokens Tutorial for a full list of available tokens.

Styling

Use the style object to style the map. You can style the map by item with the items object, as well group together items by region or category with the group property.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

You can style the map tooltips, labels, and hover states with the tooltip, label, and hoverState objects. Note that these objects can be applied at the global level in the style object or to specified items in the items object.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Adding Shapes

You have the ability to add shapes on top of a map to add interactive location points or points of interest to your map. To hook a shape to your map you must extend the shapes array with another object. Inside of that shape object you must match the map attribute to the map id or map name attribute. The last necessary step is to define x/y coordinates suffixed with lon/lat.

"shapes":[
{
    "type":"zingchart.maps",
    "options":{
        // "id": "custom_map_id", // optional id attribute
        "name":"usa",
    }
    ...      
},
{
  "type":"circle", // shapeid is OPTIONAL but smart if you are targeting events to this shape
  "id":"sd", // shapeid is OPTIONAL but smart if you are targeting events to this shape
  "x":"-117.1611lon", // hook shape based on lon/lat
  "y":"32.7157lat",   // hook shape based on lon/lat
  "map":"usa", // assigning to map name or id is necessary  
  ...

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Events

ZingChart maps are based on ZingChart shapes, which means you can use shape-related ZingChart events to extend the interactivity of your maps.

shape_click

This event fires when the user clicks on a shape.

It executes a handler function that includes the following parameters:

Parameter Type Description
id String Represents the unique id assigned to the chart <div> element, e.g., 'myChart'.
shapeid String The name of the map item.
shapeindex Number The index number of the map item.

shape_dblclick

This event fires when the user double-clicks on a shape.

It executes a handler function that includes the following parameters:

Parameter Type Description
id String Represents the unique id assigned to the chart <div> element, e.g., 'myChart'.
shapeid String The name of the map item.
shapeindex Number The index number of the map item.

shape_mousemove

This event fires whenever the user moves the mouse over a shape.

It executes a handler function that includes the following parameters:

Parameter Type Description
id String Represents the unique id assigned to the chart <div> element, e.g., 'myChart'.
shapeid String The name of the map item.
shapeindex Number The index number of the map item.

shape_mouseout

This event fires when the user mouses out of a shape.

It executes a handler function that includes the following parameters:

Parameter Type Description
id String Represents the unique id assigned to the chart <div> element, e.g., 'myChart'.
shapeid String The name of the map item.
shapeindex Number The index number of the map item.

shape_mouseover

This event fires when the user mouses over a shape.

It executes a handler function that includes the following parameters:

Parameter Type Description
id String Represents the unique id assigned to the chart <div> element, e.g., 'myChart'.
shapeid String The name of the map item.
shapeindex Number The index number of the map item.

Methods

ZingChart maps have their own custom methods. Use the maps property in the following format to access them.

zingcharts.maps.methodName();

getInfo()

This method returns information about the map.

zingchart.maps.getInfo('mapName');

It accepts the following parameters:

Parameter Type Description
mapName String The name of the map.

getItems()

This method returns a list of the map items.

zingchart.maps.getItems('mapName');

It accepts the following parameters:

Parameter Type Description
mapName String The name of the map.

getItemInfo()

This method returns information about the specified map item.

zingchart.maps.getItemInfo('mapName', 'itemName');

It accepts the following parameters:

Parameter Type Description
mapName String The name of the map.
itemName String The name of the map item.

getLonLat()

This method returns the corresponding longitude and latitude coordinates of the specified x and y positions.

zingchart.maps.getLonLat('mapName', [x, y]);

It accepts the following parameters:

Parameter Type Description
mapName String The name of the map.
[...] String An array that accepts two number values: the x and y positions, respectively.

getXY()

This method returns the corresponding x and y positions of the specified longitude and latitude coordinates.

zingchart.maps.getXY('mapName', [lon, lat]);

It accepts the following parameters:

Parameter Type Description
mapName String The name of the map.
[...] String An array that accepts two number values: the longitude and latitude coordinates, respectively.

loadGeoJSON()

This method allows you to create maps from outside GeoJSON files.

Note: It also requires you to explicitly load the module: maps-geojson.

zingchart.maps.loadGeoJSON({...});

It accepts an object with the following properties:

Property Type Description
id String The name of the custom map..
url String The map file source.
mappings Object Allows you to map property names from the GeoJSON file to ZingChart.
styling Object Allows you to style the map.
callback Function Represents the function that renders the map.

viewAll()

This method allows you to view the entire map.

zingchart.maps.viewAll('mapName');

It accepts the following parameters:

Parameter Type Description
mapName String The name of the map.

zoomIn()

This method allows you to zoom in on the map.

zingchart.maps.zoomIn('mapName');

It accepts the following parameters:

Parameter Type Description
mapName String The name of the map.

zoomOut()

This method allows you to zoom out on the map.

zingchart.maps.zoomOut('mapName');

It accepts the following parameters:

Parameter Type Description
mapName String The name of the map.

zoomTo()

This method allows you to zoom to a specified area on the map.

Note: As of Build 2.6.0, this method does not work on Windows.

zingchart.maps.zoomTo('mapName', {...});

It accepts the following parameters:

Parameter Type Description
mapName String The name of the map.
{...} Object An object that accepts the following properties:
  • zoom
  • offsetX
  • offsetY

zoomToItem()

This method allows you to zoom to a specified item on the map.

zingchart.maps.zoomToItem('mapName', 'itemName');

It accepts the following parameters:

Parameter Type Description
mapName String The name of the map.
itemName String The name of the map item.

Maps List

World

Here is the list of world maps, provided in alphabetical order.

Map (moduleName | mapName)
World Continents (maps-world-continents | world.continents)
World Countries (maps-world-countries | world.countries)

Country

Here is the list of country maps, provided in alphabetical order.

Map (moduleName | mapName)
Afghanistan (maps-afg | afg)
Albania (maps-alb | alb)
Andorra (maps-and | and)
Angola (maps-ago | ago)
Argentina (maps-arg | arg)
Armenia (maps-arm | arm)
Australia (maps-aus | aus)
Austria (maps-aut | aut)
Azerbaijan (maps-aze | aze)
Belarus (maps-blr | blr)
Belgium (maps-bel | bel)
Benin (maps-ben | ben)
Bhutan (maps-btn | btn)
Bolivia (maps-bol | bol)
Bosnia (maps-bih | bih)
Botswanna (maps-bwa | bwa)
Brazil (maps-bra | bra)
Brunei Darussalam (maps-brn | brn)
Bulgaria (maps-bgr | bgr)
Burkina Faso (maps-bfa | bfa)
Burundi (maps-bdi | bdi)
Cameroon (maps-cmr | cmr)
Canada (maps-can | can)
Central African Republic (maps-caf | caf)
Chile (maps-chl | chl)
China (maps-chn | chn)
Colombia (maps-col | col)
Congo (maps-cog | cog)
Costa Rica (maps-cri | cri)
Cote d'Ivoire (maps-civ | civ)
Croatia (maps-hrv | hrv)
Cuba (maps-cub | cub)
Cyprus (maps-cyp | cyp)
Czechia (maps-cze | cze)
Democratic Republic of the Congo (maps-cod | cod)
Denmark (maps-dnk | dnk)
Ecuador (maps-ecu | ecu)
Egypt (maps-egy | egy)
El Salvador (maps-slv | slv)
Estonia (maps-est | est)
Ethiopia (maps-eth | eth)
Finland (maps-fin | fin)
France by Region (maps-fra | fra)
France by Department (maps-fraL2 | fraL2)
French Guiana (maps-guf | guf)
Gabon (maps-gab | gab)
Gambia (maps-gmb | gmb)
Germany (maps-deu | deu)
Ghana (maps-gha | gha)
Greece (maps-grc | grc)
Guatemala (maps-gtm | gtm)
Guinea-Bissau (maps-gnb | gnb)
Guyana (maps-guy | guy)
Hungary (maps-hun | hun)
Iceland (maps-isl | isl)
India (maps-ind | ind)
Iran (maps-irn | irn)
Ireland (maps-irl | irl)
Israel (maps-isr | isr)
Italy (maps-ita | ita)
Japan (maps-jpn | jpn)
Kazakhstan (maps-kaz | kaz)
Kenya (maps-ken | ken)
Kuwait (maps-kwt | kwt)
Laos (maps-lao | lao)
Latvia (maps-lva | lva)
Liberia (maps-lbr | lbr)
Liechtenstein (maps-lie | lie)
Lithuania (maps-ltu | ltu)
Luxembourg (maps-lux | lux)
Macedonia (maps-mkd | mkd)
Mexico (maps-mex | mex)
Moldova (maps-mda | mda)
Montenegro (maps-mne | mne)
Mozambique (maps-moz | moz)
Namibia (maps-nam | nam)
Netherlands (maps-nld | nld)
New Caledonia (maps-ncl | ncl)
New Zealand (maps-nzl | nzl)
Nigeria (maps-nga | nga)
Norway (maps-nor | nor)
Oman (maps-omn | omn)
Pakistan (maps-pak | pak)
Panama (maps-pan | pan)
Papua New Guinea (maps-png | png)
Peru (maps-per | per)
Philippines (maps-phl | phl)
Poland (maps-pol | pol)
Portugal (maps-prt | prt)
Qatar (maps-qat | qat)
Romania (maps-rou | rou)
Russia (maps-rus | rus)
Rwanda (maps-rwa | rwa)
Senegal (maps-sen | sen)
Serbia (maps-srb | srb)
Slovakia (maps-svk | svk)
Slovenia (maps-svn | svn)
South Africa (maps-zaf | zaf)
South Korea (maps-kor | kor)
Spain by Autonomous Community (maps-esp | esp)
Spain by Province (maps-espL2 | espL2)
Suriname (maps-sur | sur)
Sweden (maps-swe | swe)
Switzerland (maps-che | che)
Taiwan (maps-twn | twn)
Tajikstan (maps-tjk | tjk)
Thailand (maps-tha | tha)
Tunisia (maps-tun | tun)
Turkey (maps-tur | tur)
Uganda (maps-uga | uga)
Ukraine (maps-ukr | ukr)
United Arab Emirates (maps-are | are)
United Kingdom by Country (maps-gbr | gbr)
United Kingdom by County (maps-gbrL2 | gbrL2)
United States of America (maps-usa | usa)
Uruguay (maps-ury | ury)
Uzbekistan (maps-uzb | uzb)
Venezuela (maps-ven | ven)
Vietnam (maps-vnm | vnm)
Yemen (maps-yem | yem)
Zambia (maps-zmb | zmb)
Zimbabwe (maps-zwe | zwe)

U.S. State

Here is the list of U.S. state maps, provided in alphabetical order.

Map (moduleName | mapName)
Alabama (maps-usa_al | usa_al)
Alaska (maps-usa_ak | usa_ak)
Arizona (maps-usa_az | usa_az)
Arkansas (maps-usa_ar | usa_ar)
California (maps-usa_ca | usa_ca)
Colorado (maps-usa_co | usa_co)
Connecticut (maps-usa_ct | usa_ct)
Delaware (maps-usa_de | usa_de)
District of Columbia (maps-usa_dc | usa_dc)
Florida (maps-usa_fl | usa_fl)
Georgia (maps-usa_ga | usa_ga)
Hawaii (maps-usa_hi | usa_hi)
Idaho (maps-usa_id | usa_id)
Illinois (maps-usa_il | usa_il)
Indiana (maps-usa_in | usa_in)
Iowa (maps-usa_ia | usa_ia)
Kansas (maps-usa_ks | usa_ks)
Kentucky (maps-usa_ky | usa_ky)
Louisiana (maps-usa_la | usa_la)
Maine (maps-usa_me | usa_me)
Maryland (maps-usa_md | usa_md)
Massachusetts (maps-usa_ma | usa_ma)
Michigan (maps-usa_mi | usa_mi)
Minnesota (maps-usa_mn | usa_mn)
Mississippi (maps-usa_ms | usa_ms)
Missouri (maps-usa_mo | usa_mo)
Montana (maps-usa_mt | usa_mt)
Nebraska (maps-usa_ne | usa_ne)
Nevada (maps-usa_nv | usa_nv)
New Hampshire (maps-usa_nh | usa_nh)
New Jersey (maps-usa_nj | usa_nj)
New Mexico (maps-usa_nm | usa_nm)
New York (maps-usa_ny | usa_ny)
North Carolina (maps-usa_nc | usa_nc)
North Dakota (maps-usa_nd | usa_nd)
Ohio (maps-usa_oh | usa_oh)
Oklahoma (maps-usa_ok | usa_ok)
Oregon (maps-usa_or | usa_or)
Pennsylvania (maps-usa_pa | usa_pa)
Rhode Island (maps-usa_ri | usa_ri)
South Carolina (maps-usa_sc | usa_sc)
South Dakota (maps-usa_sd | usa_sd)
Tennessee (maps-usa_tn | usa_tn)
Texas (maps-usa_tx | usa_tx)
Utah (maps-usa_ut | usa_ut)
Vermont (maps-usa_vt | usa_vt)
Virginia (maps-usa_va | usa_va)
Washington (maps-usa_wa | usa_wa)
West Virginia (maps-usa_wv | usa_wv)
Wisconsin (maps-usa_wi | usa_wi)
Wyoming (maps-usa_wy | usa_wy)

Summary

Got a question about how maps work? We are happy to help. Email support@zingchart.com or start a chat right here on this page for help.