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 = {
  areas: MapArea[];
  points: MapPoint[];
  links: MapLink[];
}

where MapArea, MapPoint, and MapLink 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 = {
  latitude: number;
  longitude: number;
}

Or, you can simply provide these values through the latitude and longitude properties of your TopoJSONMap directly.

mapFitToPoints

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

Links

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.

Link customization

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.

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

Has the same result as:

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

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 @voltera/vis/maps:

topojson	mapFeatureName	unique MapArea id	AreaDatum example
WorldMapTopoJSON, WorldMapSimplestTopoJSON, WorldMap110mAlpha	countries	ISO 2-digit country code	{ id: 'ZM' }
ChinaTopoJSON	provinces	ISO subdivision code (CN)	{ id: 'CN-ZS' }
FranceTopoJSON	regions	ISO subdivision code (FR)	{ id: 'FR-94' }
GermanyTopoJSON	regions	ISO subdivision code (DE)	{ id: 'DE-13' }
IndiaTopoJSON	regions	ISO subdivision code (IN)	{ id: 'IN-DB' }
UKTopoJSON	regions	UK ONS/GSS geocode	{ id: 'E15000002' }
USATopoJSON	states	FIPS 2-digit state code	{ id: '51' }
USCountiesTopoJSON	counties	FIPS 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

Name	Type	Description
* required property