JavaScript 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.

A ZingChart Embedded Demohttps://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.

A ZingChart Embedded Demohttps://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.

A ZingChart Embedded Demohttps://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.

A ZingChart Embedded Demohttps://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.

A ZingChart Embedded Demohttps://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.

A ZingChart Embedded Demohttps://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.

A ZingChart Embedded Demohttps://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.

A ZingChart Embedded Demohttps://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.

%long-text %text

The full name of the map item.

%short-text

The 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.

A ZingChart Embedded Demohttps://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.

A ZingChart Embedded Demohttps://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
  ...
A ZingChart Embedded Demohttps://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

This event fires when the user clicks on a shape.

It executes a handler function that includes the following parameters:

ParameterTypeDescription

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

Demo

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

It executes a handler function that includes the following parameters:

ParameterTypeDescription

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

Demo

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

It executes a handler function that includes the following parameters:

ParameterTypeDescription

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

Demo

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

It executes a handler function that includes the following parameters:

ParameterTypeDescription

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

Demo

This event fires when the user mouses over a shape.

It executes a handler function that includes the following parameters:

ParameterTypeDescription

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:

ParameterTypeDescription

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:

ParameterTypeDescription

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:

ParameterTypeDescription

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:

ParameterTypeDescription

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:

ParameterTypeDescription

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:

PropertyTypeDescription

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:

ParameterTypeDescription

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:

ParameterTypeDescription

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:

ParameterTypeDescription

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:

ParameterTypeDescription

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:

ParameterTypeDescription

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) 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.