Grid Cartogram

Grid Cartogram is a prevalent type of map for showing statistical data based on geographic location. It is a distorted form that each cell of the grid represents one subdivision. The cleanness and simplicity help users understand the information quickly without getting distracted by other elements on a normal map.

For live demos and tutorial, please see Grid Cartogram (plus a bonus Map Editor) and live COVID demos

API Reference

• GridMap(container) - Constructs a new instance of Gridmap with default settings. The container can be an svg or any g elements.
• size([width, height]) - Sets this map's dimensions to specified width and height and returns this map.
• style(style) - Overrides the default styles and return this map.
  • style.transition: a boolean value that turns on/off the transition effect
  • style.shape: the shape of map cells - square or circle
  • style.sizeByValue: all the cells have the same size by default. The map will calculate cell size based on its value if you enable this option.
  • style.cr: the attribute defines a radius on both x and y axes of rectangular map cells. The default is 4.
  • style.defaultCellColor: the default color of map cells
  • style.defaultTextColor: the default color of map cell labels
  • style.shortFormat: the default short format of the number displays inside the cell
  • style.longFormat: the default long format of the number displays below the cell when the user hovers mouse over
  • style.legendFormat: the number format of map legend
  • style.legendTitle: the title of the map legend
  • style.showOverlay: a boolean value that turns on/off the overlay (mini charts)
  • style.showOverlayLegend: a boolean value that determines whether the overlay legend is enabled
  • style.overlayLegendThreshold: the threshold of the overlay legend
  • style.showMapLegend: a boolean value that determines whether the map legend is enabled
  • style.alwaysShowOverlay: a boolean value that determines whether the overlay is always displayed or not
  • style.hideCell: a boolean value that determines whether the cell itself is visible or not. It's a combination option and should be used with the alwaysShowOverlay for displaying overlay with a clean background.
• cellPalette(palette) - Sets the color palette of cells to a specified continuous interpolator and returns this map. Default is d3.interpolateYlGnBu.
• overPalette(palette) - Sets the color palette of the overlay to a specified categorical scheme and returns this map. Default is d3.schemeTableau10.
• mapGrid(map) - Sets the map grid data and returns this map. The grid data can be easily generated by using the MapEditor below.
• data(data) - Sets the data and returns this map.
• field(field) - Sets the field names of map subdivision code, name, and values.
  • field.code: the field name of subdivision code
  • field.name: the field name of subdivision name
  • field.values: an array of field names specifying from which fields the map can gather data when rendering mini charts
  • field.total: the field name of subdivision value. It is optional if you have specified the field.values unless you need to show a different number other than the total.
• customSquareOverlay(f) - Sets the custom function for overriding the square overlay renderer. There are three arguments for the custom function:
  • g - the g element contains the mini chart
  • getSize - the function to get the size of the mini chart. It is only needed when you customize the overlay with style.sizeByValue turned on.
  • color - the color scale of the values
• customCircleOverlay(f) - Sets the custom function for overriding the circle overlay renderer.
• processMap() - This is only needed when you customize the overlay with style.sizeByValue turned off. For details, please see the tutorial above.
• render() - Renders the map and returns this instance.