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 1.6.5​

Points can have two kinds of labels: central and bottom. The label at the center of the point can be set using the pointLabel property. This label will fit into the point, so it is supposed to be short.

Deprecated

The pointLabelPosition property has been deprecated in version 1.6.5. Use pointLabel for central labels and pointBottomLabel for bottom labels instead.

Central Label​

The central label is displayed at the center of each point. Use the pointLabel property to set it:

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

const pointLabel = (d: MapPoint) => `${(d.population / 1000000).toFixed(1)}M`

You can control the color of central labels with the pointLabelColor config property. By default, the label color will be set to a CSS variable, depending on the point brightness, either to --vis-map-point-inner-label-text-color-light or to --vis-map-point-inner-label-text-color-dark.

Bottom Label​

The bottom label appears below the point and can be longer. It's configurable via the pointBottomLabel property:

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

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

Clustered Color Map​

When you have multiple points close together, TopoJSONMap can automatically cluster them for better visualization. Enable clustering by setting the clustering property to true.

clustering={true}

Points will automatically cluster and uncluster as you zoom in or out. When you click on a cluster, you can expand it to see the individual points (if clusterExpandOnClick is enabled) or zoom in until the cluster breaks apart.

Cluster Color and Radius​

You can customize cluster appearance with the clusterColor and clusterRadius properties. These properties accept either constant values or accessor functions that will receive TopoJSONMapClusterDatum as an argument, which has a clusterPoints property containing all points within that cluster.

clusterColor="#4A46B5"
clusterRadius={(d) => 10 + 3 * Math.sqrt(d.clusterPoints.length)}

The default cluster color comes from the --vis-map-cluster-default-fill-color CSS variable.

Cluster Labels 1.6.5​

By default, clusters display the number of contained points in the center. You can override this with the clusterLabel property. The clusterBottomLabel property allows you to set the bottom label.

clusterLabel={d => `${d.pointCount}`}
clusterBottomLabel={d => `${d.clusterPoints.length} locations`}

Similar to point labels, you can set the color of cluster labels with the clusterLabelColor config property.

Clustering Distance​

Control how close points need to be to cluster together with the clusteringDistance property. The value represents the radius in pixels within which points will be grouped into a cluster.

clusteringDistance={50}

Expand on Click​

If you want clusters to never expand on click, you can set clusterExpandOnClick to false. In that case, when you click on a cluster, the map will keep zooming in until the zoom level is high enough for the cluster to break.

clusterExpandOnClick={false}

Color Map with Clusters​

If you're using TopoJSONMapPointShape.Circle or TopoJSONMapPointShape.Ring as a point shape, and your points have multiple values of the same kind associated with them, you can show the distribution of those values as a tiny pie or donut diagram.

Let's say you want to show server status with different categories, and your data point looks like:

type MapPoint = {
  ...
  normal: number;
  blocked: number;
  warning: number;
}

You can use the colorMap property to define the color (and custom CSS class if necessary) for the corresponding pie/donut segments:

const colorMap = {
  normal: { color: '#26BDA4' },
  blocked: { color: '#9876AA' },
  warning: { color: '#FFD651', className: 'warning' },
}

When clustering is enabled with a color map, clusters automatically aggregate the values from all contained points. Each cluster is rendered as a donut chart, where each segment represents the sum of values for that category across all points in the cluster. The thickness of the donut ring can be customized using the clusterRingWidth property for clusters and pointRingWidth for individual 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

Flow Map​

TopoJSONMap can display animated particles flowing between points on the map, similar to how data flows in a network. This is useful for visualizing connections, data transfers, or any directional relationships between locations.

Data​

To use flow animations, provide flow data in the links array. Each flow should have source and target coordinates:

type FlowDatum = {
  sourceLongitude: number;
  sourceLatitude: number;
  targetLongitude: number;
  targetLatitude: number;
}

You can also use custom accessor functions by providing them to: sourceLongitude, sourceLatitude, targetLongitude, and targetLatitude.

To enable animated particles, set enableFlowAnimation to true:

const data = {
  points: [
    { id: 'NYC', latitude: 40.7128, longitude: -74.0060 },
    { id: 'LON', latitude: 51.5074, longitude: -0.1278 },
  ],
  links: [
    {
      sourceLongitude: -74.0060,
      sourceLatitude: 40.7128,
      targetLongitude: -0.1278,
      targetLatitude: 51.5074,
    }
  ]
}

<TopoJSONMap
  data={data}
  enableFlowAnimation={true}
/>

Particles​

TopoJSONMap allows you to customize the appearance and behavior of the animated particles:

Color​

The color of the particles can be set using the flowParticleColor property:

flowParticleColor="#54bf31"

Radius​

You can change the radius of the particles with the flowParticleRadius property:

flowParticleRadius={3}

Speed​

The speed of the particles can be controlled using the flowParticleSpeed property. The value is in arbitrary angular units; we recommend it to be in the range of [0, 0.2].

flowParticleSpeed={0.08}

Density​

The flowParticleDensity property sets the density/frequency of the flying particles. The recommended range is [0, 1].

flowParticleDensity={0.6}

Flow Source Points​

You can customize the appearance of the flow source points:

Color​

The color of the flow source can be customized using the sourcePointColor configuration property:

sourcePointColor="#4A46B5"

Radius​

The sourcePointRadius property sets the radius of the source point:

sourcePointRadius={5}

Events​

The flow source points have configurable callback functions for mouse events:

/** Flow source point click callback function. Default: `undefined` */
onSourcePointClick: (f: FlowDatum, x: number, y: number, event: MouseEvent) => void;
/** Flow source point mouse over callback function. Default: `undefined` */
onSourcePointMouseEnter: (f: FlowDatum, x: number, y: number, event: MouseEvent) => void;
/** Flow source point mouse leave callback function. Default: `undefined` */
onSourcePointMouseLeave: (f: FlowDatum, event: MouseEvent) => void;

You can display both static links (lines) and animated flow particles simultaneously:

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' }

Tooltip​

Points​

TopoJSONMap accepts a Tooltip instance as a config property. If you want to add a tooltip to the points and clusters, you can use the [TopoJSONMap.selectors.point] selector in your Tooltip configuration for both.

Clustered points with color map​

When using clustering with a color map, you can show detailed information about the distribution of values in the tooltip:

Map areas​

If you have area data on your map, you can make the tooltip work with it by using the [TopoJSONMap.selectors.feature] selector. The tooltip callback will be called when hovering over map features (areas).

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.

Component Props​

NameTypeDescription
* required property