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


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.


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

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


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 = [
const areaData = => ({ 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 ( {
case 'AU': return 'red'
case 'BR': return 'blue'
case 'CN': return 'green'


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


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:


To set the initial zoom factor.


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

topojsonmapFeatureNameunique MapArea idAreaDatum example
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' }


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;
/* Dark Theme */
--vis-dark-map-feature-color: #5b5f6d;
--vis-dark-map-boundary-color: #2a2a2a;
--vis-dark-map-point-label-text-color-dark: #fff;

Component Props

* required property