Interactive Maps

Note: See our Maps Gallery for inspiration on all the different map possibilities.

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 below 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 value to the map name (e.g., world.continents).

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

{
  shapes: [
    {
      type: 'zingchart.maps',
      options: {
        name: 'usa'
      }
    }
  ]
}

Map-specific Properties

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. With the exception of the world countries map (more below), provide the items to include as comma separated strings.

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

{
  options: {
    name: 'usa_ca',
    items: ['SP', 'KE', 'SR', 'VE', 'LO', 'SB', 'OR', 'RI', 'SD', 'IM'],
  }
}
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.

{
  options: {
    name: 'world.countries', // Note that the below property works with world.countries only.
    groups: ['NORTHAMERICA'],
  }
}
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 comma separated strings.

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

{
  options: {
    name: 'usa',
    ignore: ['AK', 'HI']
  }
}
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.

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.

{
  options: 
    {
      name: 'usa',
      bbox: [-125.393, 42.998, -113.125, 31.536]
    }
}
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.

{
  options: 
    {
      name: 'usa_ca',
      scale: false
    }
}
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.

{
  options: {
    zoom: 2,
    offsetX: -200,
    offsetY: -200,
  }
}
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 scrolling properties to enable (true) or disable (false) these settings.

{
  options: {
    zooming: false,
    panning: false,
    scrolling: false,
}
https://app.zingsoft.com/demos/embed/H7V6QQXV
https://app.zingsoft.com/demos/embed/H7V6QQXV

To style the zoom controls, add a style object with a controls object inside. 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. The default is 'tl'.

{
  options: {
    style: {
      controls: {
        placement: 'tr', //tl (default), tr, bl, br
        visible: true,
      }
    }
  }
}
https://app.zingsoft.com/demos/embed/7A45T037
https://app.zingsoft.com/demos/embed/7A45T037

Further Customization

Once you have your basic map, you can customize and style it to fit your data visualization needs.

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

Note: 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.

{
  options: {
    style: {
      items: {
        //Northeast:
        CT: {
          group: 1,
          backgroundColor: '#FFCDD2',
          hoverState: {
            backgroundColor: '#EF9A9A'
          }
        }
      }
    }
  }
}
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.

{//shortened for brevity- click on following map demo to see full configuration
  options: {
    style: {
      label: {
        visible: false
      },
      tooltip: {
        text: '%data-region:<br>%text',
        alpha: 0.7,
      },
      items: {
        //Southern California:
        SP: {
          group: 2,
          hoverState: {
            backgroundColor: '#FFD54F'
          }
        }
      }
    }
  }
}
https://app.zingsoft.com/demos/embed/QV5HH3H2
https://app.zingsoft.com/demos/embed/QV5HH3H2

Adding Shapes

Add shapes on top of a map to add interactive location points or points of interest. 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
  ...
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

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
https://app.zingsoft.com/demos/embed/3FEIXJBN
https://app.zingsoft.com/demos/embed/3FEIXJBN

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

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

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
https://app.zingsoft.com/demos/embed/658PMMQI
https://app.zingsoft.com/demos/embed/658PMMQI

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

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

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
https://app.zingsoft.com/demos/embed/23Z0KCOR
https://app.zingsoft.com/demos/embed/23Z0KCOR

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

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
https://app.zingsoft.com/demos/embed/8KPKU1WE
https://app.zingsoft.com/demos/embed/8KPKU1WE

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

loadGeoJSON()

This method allows you to create maps from outside GeoJSON files. It 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
https://app.zingsoft.com/demos/embed/5C36IEZC
https://app.zingsoft.com/demos/embed/5C36IEZC

loadTopoJSON()

This method allows you to create maps from outside TopoJSON files. It requires you to explicitly load the module: maps-topojson.

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

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 TopoJSON file to ZingChart
styling Object Allows you to style the map
callback Function Represents the function that renders the map
https://app.zingsoft.com/demos/embed/5G631L8T
https://app.zingsoft.com/demos/embed/5G631L8T

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

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

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

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
https://app.zingsoft.com/demos/embed/8ANK05LL
https://app.zingsoft.com/demos/embed/8ANK05LL

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

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
Botswana (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
Malta (maps-mlt | mlt) Demo
Morocco (maps-mar | mar) 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
Saudi Arabia (maps-sau | sau) 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
Tajikistan (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