Interactive Maps

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

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

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

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

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

{
  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:

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:

shape_dblclick

This event fires when the user double-clicks on a shape. It executes a handler function that includes the following parameters:

shape_mousemove

This event fires whenever the user moves the mouse over a shape. It executes a handler function that includes the following parameters:

shape_mouseout

This event fires when the user mouses out of a shape. It executes a handler function that includes the following parameters:

shape_mouseover

This event fires when the user mouses over a shape. It executes a handler function that includes the following parameters:

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:

getItems()

This method returns a list of the map items.

zingchart.maps.getItems('mapName');

It accepts the following parameters:

getItemInfo()

This method returns information about the specified map item.

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

It accepts the following parameters:

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:

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:

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:

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:

viewAll()

This method allows you to view the entire map.

zingchart.maps.viewAll('mapName');

It accepts the following parameters:

zoomIn()

This method allows you to zoom in on the map.

zingchart.maps.zoomIn('mapName');

It accepts the following parameters:

zoomOut()

This method allows you to zoom out on the map.

zingchart.maps.zoomOut('mapName');

It accepts the following parameters:

zoomTo()

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

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

It accepts the following parameters:

zoomToItem()

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

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

It accepts the following parameters:

Maps List

World

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

Country

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

U.S. State

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