MapView

The MapView is a component that renders a map with various geospatial data layers.

OverviewProperties

Import

import { MapView } from '@dynatrace/strato-geo';

Use cases

The minimal representation of a MapView component is a base layer that contains a world map.

The height of the MapView component must be set explicitly using the height prop. The width of the MapView component will be determined by the width of the parent container.

CodeSandbox

Controlled and uncontrolled states

The MapView component can be used in both controlled and uncontrolled states. In the uncontrolled state it's possible to configure the initial longitude, latitude and zoom level of the map using initialViewState prop. By default, the map will be centered on the equator and zoomed out to show the whole world.

CodeSandbox

In the controlled state, user can attach state handlers to the MapView component using the onViewStateChange prop, as well as dynamically change the longitude, latitude and zoom level of the map.

CodeSandbox

Data layers

The MapView component supports rendering of data layers on the map using the different subcomponents. Multiple data layers of the same type can be rendered. The order of the data layers is determined by the order of the subcomponents of the MapView component.

For detailed documentation about each data layer, please refer to the respective docs pages.

Color configuration

All data layers support multiple ways of color configuration. In general, there are two ways of configuring colors: granular color configuration per layer using a color prop, and color configuration using a legend.

Granular color configuration per layer

For a granular color customization of a single layer, layer's color prop should be used. It supports a string or a callback that returns a string. The string value should be any valid CSS color, including rgba, hex, transparent, or a color name.

If string is provided, it will be used as a color for all data points in the layer, while providing a callback that receives a data point as an argument allows to customize the color per data point.

CodeSandbox

Color configuration using a legend

Using predefined legend subcomponents it's possible to easily set an advanced colors configuration for multiple data layers at once.

There are three legend subcomponents that can be used to configure colors of the data layers: SequentialLegend, ThresholdLegend, and CategoricalLegend.

To connect a data layer to the legend, a color property of the layer should be set to legend string. All data layers with legend color will be colored according to the legend configuration. Only one legend subcomponent can be used at a time.

As most of the data layer subcomponents have minimal required data properties of latitude and longitude, the value associated with the data point must be provided using the valueAccessor prop. The string provided as a value accessor will be used to access the property of the data point object. Be aware, that while some legends expect the value to be a numeric (SequentialLegend and ThresholdLegend), other expect a string value (CategoricalLegend).

Sequential legend

The SequentialLegend subcomponent allows to automatically split the value range of the data points into multiple even-sized buckets and assign a color to each bucket. To configure the sequential legend, value boundaries must be using the min and max numeric props. To define a color palette to be used, a colorPalette prop should be set. The colorPalette prop supports custom color palettes as an array of string values, as well as variety of predefined color palettes ( see coloring for more details).

The data layer's valueAccessor prop must reference a numeric property of the data point object.

CodeSandbox

Threshold legend

The ThresholdLegend subcomponent is similar to the SequentialLegend, but allows to define custom value ranges for each bucket. To configure the threshold legend, an array of ranges must be provided using the ranges prop. Each range must contain min and max props that define the range boundaries, and a color prop.

The data layer's valueAccessor prop must reference a numeric property of the data point object.

CodeSandbox

Categorical legend

The CategoricalLegend subcomponent allows mapping of a string value to a specific color, thus creating a categorical color mapping. To configure the categorical legend, an array of category names must be provided using the categories prop, and a color palette using the colorPalette prop. To use a custom color palette, an array of string values must be provided.

When passing a predefined color palette, a key of the color palette item will be mapped to the equal category name (if found), and a value of the color palette item will be used as a color. If a category name is not found in the color palette, a default color of the data layer will be used.

The categorical legend supports legend items interactions. When hovering on a legend item name, data points of this category will be highlighted on the map. When hovering on a legend item icon, the opposite will happen - all other categories will be highlighted. When clicking left mouse button (LButton) on a legend item name, all other categories will be hidden.

CodeSandbox

Legend shared properties

All legend subcomponents support the following shared properties:

• position - defines the position of the legend on the map. Supported options are right, bottom, and auto. The default value is auto, which will place the legend on the right side of the map if the map width is greater than the height, and on the bottom of the map otherwise.
• hidden - defines whether the legend should be hidden. The legend is visible by default.

Disputed borders and disabled state

The MapView component, when used in the Dynatrace infrastructure, supports rendering of disputed borders. Read permissions should be set for fetching disputed borders and map’s disabled state, there is more information about permission scopes. Depending on country code provided in the tenant configurations, relevant disputed borders (if any) for that country will be rendered, if not the default map will be shown.

The MapView component has an automatic disabled state. When set the respective setting is configured in the client environment, the MapView component will display a predefined message about the disabled state instead of the map.

Chart interactions

The MapView chart interaction provide flexible and easy way to explore your data. To incorporate these interactions, the ChartInteractions component must be added to the MapView. The chart interaction can then either be triggered using keyboard shortcuts, mouse interactions, programmatically, or by the optional chart toolbar. To enable the toolbar with the chart interactions, the ChartToolbar subcomponent must be added to the MapView. The initial position of the toolbar can be set using the placement prop.

Zoom and pan

There is a number of zoom interactions available for the MapView component.

In order to enable either of these zoom options on a chart it is necessary to add the ChartInteractions.Zoom subcomponent to the ChartInteractions component.

It's possible to zoom in/out when hovering a cursor over the chart and using either a scroll wheel, pinching on a trackpad, double click LButton, or by clicking LButton and holding Shift while dragging the cursor. To reset the zoom to the initial state, a ChartToolbar reset button must be clicked.

A ChartToolbar component also provides a zoom-to-fit button that, when clicked, will zoom the map to fit all the data points from all the data layers.

A zoom level determines how much of the world is visible on a map.There are 23 zoom levels in total supported, with 0 being the lowest zoom level (fully zoomed out) and 22 being the highest (fully zoomed in).

Zoom level breakdown by what is visible on the map:

• 0: The whole world
• 3: A continent
• 4: Large islands
• 6: Large rivers
• 10: Large rivers
• 15: Buildings

To pan a map, click and hold LButton and drag the cursor.

CodeSandbox

Download data as CSV

All the data from data layers can be download in CSV format using a toolbar button. To enable this feature, a ChartToolbar subcomponent with ChartToolbar.DownloadData inside of it must be provided. The CSV file will contain two required columns: latitude and longitude. Depending on the shape of the data point, all additional properties will be added as columns to the CSV file.

CodeSandbox

It's also possible to programmatically trigger the download of the CSV file by calling the downloadData method on the MapView instance reference.

CodeSandbox

Add Tooltip

The MapView component has an optional tooltip that displays additional data point information when hovering over data points from any of the data layers. To enable the tooltip a Tooltip subcomponent should be used inside the data layer component (e.g. DotLayer.Tooltip, BubbleLayer.Tooltip, etc.). When a Tooltip subcomponent is provided without any children, the default tooltip will be used. Every data layer has its own default tooltip due to data shape difference.

Customize Tooltip

Tooltip sections

It's possible to customize the tooltip by providing a custom template that can consist of tooltip sections, items, and atoms. The Tooltip comprises three main sections: Tooltip.Header, Tooltip.Body, and Tooltip.Footer. Each section can contain different subsections, items, and atoms.

The Tooltip.Header serves as the topmost part of the tooltip and it always contains a divider at its bottom. It is also possible to set an optional Tooltip.Subheader within a Tooltip.Header to add additional information that is rendered in a new block.

The Tooltip.Body is the central and interactive part of the tooltip. The Tooltip.Body content is virtualized by default to improve performance, and it can be disabled by setting the virtualization prop to false.

In order to have a proper virtualization, the itemHeight prop, which is the height of every Tooltip.Item subcomponent within the Tooltip.Body, is needed.

The Tooltip.Footer subcomponent always includes a divider at the top. This section can be used to display the total number of items available or any other contextual information.

CodeSandbox

Items

Tooltip.Items are independent components that can be placed in the header, body, or footer sections. Each of these items serve a specific purpose and acts as a flexbox. It is recommended nesting Tooltip.Symbol, Tooltip.Content, and Tooltip.Value within the Tooltip.Item so that the space will be distributed evenly.

CodeSandbox

The tooltip template can nest any custom HTML and styles can be overridden.

CodeSandbox

Tooltip Atoms

Multiple Tooltip.Item components can be combined in various ways, and the space distribution is flexible, allowing their arrangement according to preferences.

CodeSandbox

Chart states

Loading

The MapView component is able to show the default loading indicator setting the loading prop to true.

CodeSandbox

Error

The <ErrorState /> subcomponent can be used to customise the error message that will be displayed when an error occurs in the MapView component.

CodeSandbox