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'],
}
}
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'],
}
}
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']
}
}
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]
}
}
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
}
}
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,
}
}
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,
}
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,
}
}
}
}
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'
}
}
}
}
}
}
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'
}
}
}
}
}
}
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
...
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. 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 |
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 |
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:
|
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) 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 |