Skip to main content

TopoJSON Map

Basic Configuration​

The TopoJSONMap is a map that uses TopoJSON as its underlying data. The basic configuration is:

note

The remaining examples will use WorldMapTopoJSON for the topojson configuration. Check out this section to learn about other available maps.

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 = {
  area: 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 Customization​

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.

Custom Point Labels​

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. 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;
}

Area customization​

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

  • areaColor
  • areaCursor

Projection​

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.

heatmapModeZoomLevelThreshold​

To lower or raise the threshold hat 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
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]: {},
}

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