Interactive Maps

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.

https://app.zingsoft.com/demos/embed/FZP37Z6I
https://app.zingsoft.com/demos/embed/FZP37Z6I

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

https://app.zingsoft.com/demos/embed/A94NMHXK
https://app.zingsoft.com/demos/embed/A94NMHXK

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.

https://app.zingsoft.com/demos/embed/N4HAST7S
https://app.zingsoft.com/demos/embed/N4HAST7S

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.

https://app.zingsoft.com/demos/embed/4GNE4X2B
https://app.zingsoft.com/demos/embed/4GNE4X2B

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.

https://app.zingsoft.com/demos/embed/179CHC4P
https://app.zingsoft.com/demos/embed/179CHC4P

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.

https://app.zingsoft.com/demos/embed/PIRTOT02
https://app.zingsoft.com/demos/embed/PIRTOT02

Zooming, Panning, Scrolling

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

https://app.zingsoft.com/demos/embed/H7V6QQXV
https://app.zingsoft.com/demos/embed/H7V6QQXV

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.

https://app.zingsoft.com/demos/embed/7A45T037
https://app.zingsoft.com/demos/embed/7A45T037

Tokens

Maps use the following tokens:

TokenDescription
%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.Demo
%long-text %textThe full name of the map item.Demo
%short-textThe abbreviated name of the map item.Demo

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.

https://app.zingsoft.com/demos/embed/M7A1CCEF
https://app.zingsoft.com/demos/embed/M7A1CCEF

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.

https://app.zingsoft.com/demos/embed/QV5HH3H2
https://app.zingsoft.com/demos/embed/QV5HH3H2

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 mapattribute 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
  ...
https://app.zingsoft.com/demos/embed/4Y11QZFI
https://app.zingsoft.com/demos/embed/4Y11QZFI

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

Demo

This event fires when the user clicks on a shape.

It executes a handler function that includes the following parameters:

ParameterTypeDescription
idStringRepresents the unique id assigned to the chart <div> element, e.g., 'myChart'.
shapeidStringThe name of the map item.
shapeindexNumberThe index number of the map item.

shape_dblclick

Demo

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

It executes a handler function that includes the following parameters:

ParameterTypeDescription
idStringRepresents the unique id assigned to the chart <div> element, e.g., 'myChart'.
shapeidStringThe name of the map item.
shapeindexNumberThe index number of the map item.

shape_mousemove

Demo

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

It executes a handler function that includes the following parameters:

ParameterTypeDescription
idStringRepresents the unique id assigned to the chart <div> element, e.g., 'myChart'.
shapeidStringThe name of the map item.
shapeindexNumberThe index number of the map item.

shape_mouseout

Demo

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

It executes a handler function that includes the following parameters:

ParameterTypeDescription
idStringRepresents the unique id assigned to the chart <div> element, e.g., 'myChart'.
shapeidStringThe name of the map item.
shapeindexNumberThe index number of the map item.

shape_mouseover

Demo

This event fires when the user mouses over a shape.

It executes a handler function that includes the following parameters:

ParameterTypeDescription
idStringRepresents the unique id assigned to the chart <div> element, e.g., 'myChart'.
shapeidStringThe name of the map item.
shapeindexNumberThe 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()

Demo

This method returns information about the map.

zingchart.maps.getInfo('mapName');

It accepts the following parameters:

ParameterTypeDescription
mapNameStringThe name of the map.

getItems()

Demo

This method returns a list of the map items.

zingchart.maps.getItems('mapName');

It accepts the following parameters:

ParameterTypeDescription
mapNameStringThe name of the map.

getItemInfo()

Demo

This method returns information about the specified map item.

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

It accepts the following parameters:

ParameterTypeDescription
mapNameStringThe name of the map.
itemNameStringThe name of the map item.

getLonLat()

Demo

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:

ParameterTypeDescription
mapNameStringThe name of the map.
[...]StringAn array that accepts two number values: the x and y positions, respectively.

getXY()

Demo

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:

ParameterTypeDescription
mapNameStringThe name of the map.
[...]StringAn array that accepts two number values: the longitude and latitude coordinates, respectively.

loadGeoJSON()

Demo

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:

PropertyTypeDescription
idStringThe name of the custom map..
urlStringThe map file source.
mappingsObjectAllows you to map property names from the GeoJSON file to ZingChart.
stylingObjectAllows you to style the map.
callbackFunctionRepresents the function that renders the map.

viewAll()

Demo

This method allows you to view the entire map.

zingchart.maps.viewAll('mapName');

It accepts the following parameters:

ParameterTypeDescription
mapNameStringThe name of the map.

zoomIn()

Demo

This method allows you to zoom in on the map.

zingchart.maps.zoomIn('mapName');

It accepts the following parameters:

ParameterTypeDescription
mapNameStringThe name of the map.

zoomOut()

Demo

This method allows you to zoom out on the map.

zingchart.maps.zoomOut('mapName');

It accepts the following parameters:

ParameterTypeDescription
mapNameStringThe name of the map.

zoomTo()

Demo

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:

ParameterTypeDescription
mapNameStringThe name of the map.
{...}Object

An object that accepts the following properties:

  • zoom
  • offsetX
  • offsetY

Demo

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

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

It accepts the following parameters:

ParameterTypeDescription
mapNameStringThe name of the map.
itemNameStringThe 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) Demo
World Countries (maps-world-countries | world.countries) Demo

Country

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

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

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

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.