Skip to main content

TopoJSON Map

The TopoJSONMap component is a map that is renders topological geo-data from the TopoJSON data format. You can provide your own custom topojson or use one of the pre-configured topojson files provided in @unovis/ts/maps. In addition to custom topologies, TopoJSONMap supports a variety of features including the ability to add points and links, feature customization, zooming, alternate map projections and more.

Basic Configuration​

Map Data​

There are three main building blocks that can make up the data supplied to TopoJSONMap:

  • point, a geographical coordinate
  • link, a graph edge that connects two points
  • area, a geographical area

The container for TopoJSONMap accepts data in the form of an Object with these three building blocks as keys mapped to their data arrays, like so:

type MapData = {
  points: MapPoint[];
  links: MapLink[];
  areas: MapArea[];
}

where MapPoint, MapLink and MapArea, are custom types that represent map data. Keep reading to learn more about the minimum configurations for these types.

Points​

A minimum viable datatype of the objects provided to the points attribute is:

type MapPoint = {
  id: string;
  latitude: number;
  longitude: number;
  color: string;
}

You can also provide these values through the latitude, longitude, pointId, and color properties.

mapFitToPoints​

Enabling mapFitToPoints will automatically adjust the map's zoom level to fit all the points provided.

Before:

After:

Point Styling​

The following TopoJSONMap properties accept accessor functions to customize the appearance of your points:

  • pointColor
  • pointCursor
  • pointRadius
  • pointStrokeWidth

Point Labels​

You can provide labels with the pointLabel attribute, which accepts a StringAccessor function to be called on each MapPoint datum.

For example, consider the following type and accessor function:

type MapPoint = {
  id: string;
  latitude: number;
  longitude: number;
  city: string;
}

const pointLabel = (d: MapPoint) => d.city

Point Label Styling​

The following TopoJSONMap properties can further customize your Point Label.

  • pointLabelPosition
  • pointLabelTextBrighnessRatio

Example: Custom Points​

A minimum viable data type of the objects provided to the links attribute contains the keys source and target, which correspond to the points the link will connect. Most commonly, the pointId.

type MapLink = {
  source: string | number | MapPoint;
  target: string | number | MapPoint;
}

Or, you can simply provide these values through the linkSource and linkTarget properties.

You can further customize the map Links with the following properties:

  • linkColor
  • linkCursor
  • linkWidth

Areas​

To work with features in the TopoJSONMap, all you need is a unique id which is defined in the chart's topojson definition or an areaId accessor function. For example, in our WorldMapTopoJSON topojson, every country has a unique id that corresponds to the ISO 3166-1 alpha-2 country code. See our topojson configuration section for more details.

type MapArea = {
  id: string;
}

As a basic example, let's say you have an array of countries created from ISO codes:

const countryCodes = [
  'AU','BR','CN','EG','FR','IN','JP','MX','NO','PE','PH','RU','TZ','US'
]
const areaData = countryCodes.map(id => ({ id }))
const data = { areas: areaData }

The provided countries will be highlighted according to their color defined in the topojson file:

Custom Color​

You can override the default area colors by including a color property in AreaDatum or by providing an areaColor accessor function.

Method 1: Through AreaDatum property​

const data = {
  points: [],
  links: [],
  areas: [
    { id: 'AU', color: 'red' },
    { id: 'BR', color: 'blue' },
    { id: 'CN', color: 'green' },
  ]
}

Method 2: Through areaColor accessor function​

const areaColor = (d: AreaDatum) => {
  switch (d.id) {
    case 'AU': return 'red'
    case 'BR': return 'blue'
    case 'CN': return 'green'
  }
}

The result:

Note: If areaColor is provided, it will override the color property in AreaDatum.

Projections​

You can provide a projection for your TopoJSONMap with a MapProjection instance. See D3's geo projections for more information.

Zoom​

By default, zooming is enabled for a TopoJSONMap component. You can disable it by setting the disableZoom property to true.

For further customization, you can configure the following zoom properties:

zoomFactor​

To set the initial zoom factor.

zoomExtent​

zoomExtent represents the range [a,b] which your map can zoom in and out, where [a, b] are the minimum and maximum zoom factors, respectively.

zoomDuration​

zoomDuration is the duration of the animation on when zooming in on your TopoJSONMap.

Heatmap Mode​

For datasets with a lot of points, you can enable heatmapMode

You can customize the appearance of your heat map blur with the heatmapModeBlurStdDeviation property.

To lower or raise the threshold that will disable the blur effect of your heat map, use the the heatmapModeZoomLevelThreshold property. You can provide a zoom level, (i.e. 2 for 2x zoom), that once reached, that will no longer display the blur effect.

TopoJSON Configuration​

In order for the TopoJSONMap component to render properly, the topojson property and a valid mapFeatureName must be provided. The mapFeatureName corresponds to the type of unique area ids in your data.

TopoJSONs currently available in @unovis/ts/maps:

topojsonmapFeatureNameunique MapArea idAreaDatum example
WorldMapTopoJSON,
WorldMapSimplestTopoJSON,
WorldMap110mAlpha		countriesISO 2-digit country code{ id: 'ZM' }
ChinaTopoJSONprovincesISO subdivision code (CN){ id: 'CN-ZS' }
FranceTopoJSONregionsISO subdivision code (FR){ id: 'FR-94' }
GermanyTopoJSONregionsISO subdivision code (DE){ id: 'DE-13' }
IndiaTopoJSONregionsISO subdivision code (IN){ id: 'IN-DB' }
UKTopoJSONregionsUK ONS/GSS geocode{ id: 'E15000002' }
USATopoJSONstatesFIPS 2-digit state code{ id: '51' }
USCountiesTopoJSONcountiesFIPS 5-digit county code{ id: '53033' }

Events​

import { TopoJSONMap } from '@unovis/ts'

const events = {
  [TopoJSONMap.selectors.point]: {},
  [TopoJSONMap.selectors.feature]: {},
}

CSS Variables​

The TopoJSONMap component supports additional styling via CSS variables that you can define for your visualization container.

All supported CSS variables and their default values
--vis-map-feature-color: #dce3eb;
--vis-map-boundary-color: #ffffff;
--vis-map-point-label-text-color-dark: #5b5f6d;
--vis-map-point-label-text-color-light: #fff;
--vis-map-point-label-font-weight: 600;
--vis-map-point-label-font-size: 12px;
--vis-map-point-label-font-family
 
/* Dark Theme */
--vis-dark-map-feature-color: #5b5f6d;
--vis-dark-map-boundary-color: #2a2a2a;
--vis-dark-map-point-label-text-color-dark: #fff;
--vis-dark-map-point-label-text-color-light:#5b5f6d;

Component Props​

NameTypeDescription
* required property