TreeMap

The TreeMap visualizes the distribution of hierarchical data. It uses nested rectangles of different sizes and colors to show how much each category or subcategory contributes to the whole data set.

OverviewProperties

Import

import { TreeMap } from '@dynatrace/strato-components-preview/charts';

Use cases

The TreeMap component requires a structured tree object containing hierarchical data, with an optional unit specified as a string. This data should support two levels of categories: ClusterNode and LeafNode.

Structure

Tree Object: The root of the dataset, containing the overall structure.

• value: A numerical value representing the total value at the root level. - nodes: An array of cluster nodes. - name: An optional string representing the name of the root node.

Cluster Nodes: Each parent node represents a category and includes:

• name: A string representing the name of the category. - value: A numerical value representing the total value of the category. - nodes: An array of leaf nodes.

Leaf Nodes: Each child node represents a sub-category and includes:

• name: A string representing the name of the sub-category. - value: A number representing the value of the sub-category.

The displayed data can be adjusted by setting limits. These limits can be defined using the min and max properties. Setting those limits is particularly useful when displaying numerical values in the legend nameAccessor='value'

The min property can use the data-min value, and the max property can use the data-max value. These special values provide detailed control over the boundaries.

By default, the data-min value is used for the min property, and the data-max value is used for the max property. These settings automatically determine the minimum and maximum values for the nodes in the chart.

Additionally, the min and max properties can also accept numeric values. This allows you to manually set specific numerical limits for the data display, giving you even more control over the range of data shown in the chart.

{
  tree: {
    name: '',
    value: 0,
    nodes: [
      {
        name: 'India',
        value: 117200000,
        nodes: [
          {
            name: 'Delhi',
            value: 27000000,
          }
        ]
      }
    ]
  }
}

Learn more about the data format here.

CodeSandbox

Size

By default, the chart will use all the available container size up to a maximum height of 300 pixels. This maximum height can be changed by providing a value in the height prop of the TreeMap instance. If a number is passed to this prop without any unit specified, it will be treated as px.

CodeSandbox

Series actions

A series action is a creator-defined interaction with a given node in the chart. The default interaction included is copying a node name. Inspecting the underlying data of said node is an example of a basic creator-defined action. In order to enable chart interactions, the ChartSeriesAction subcomponent needs to be appended within the TreeMap. More subcomponents can be added within this component, for instance ChartSeriesAction.Item, where you can provide a custom action that will appear in the legend menu. That action can execute any custom logic in its onSelect callback or get disabled via a disabled prop.

CodeSandbox

Legend

The purpose of the legend is to provide additional identifying information for the chart, without needing to interact with the legend directly.

Visibility

The legend of the TreeMap is shown by default. In order to hide or show the legend, you need to set the value of legend.hidden on the subcomponent.

Position

By default, the position of the legend of the TreeMap is set automatically. This option prioritizes the legend placement to the right of the chart area. When the chart width is reduced, the legend is repositioned to the area beneath the chart. It is also possible to explicitly set the chart's legend position to right or bottom with the position prop.

Legend ratio

By default, the legend occupies 25% of the container width, in the case where the legend is positioned on the right and 25% of the container height if the legend position is on the bottom.

It is possible to override the default legend ratio by setting a custom percentage value for the ratio prop. The expected value is in the range of 5-80. Values out of expected ranges will roll back to the default legend ratio.

CodeSandbox

Formatter

The TreeMap component expects a structured tree object with a value and an optional unit, by default this optional unit will be appended to the specified value, if it is included. There are two other options in the formatter that allow for greater customization. The first option enables you to prepend the unit to the value, while the second option enables you to ignore the original unit and append a custom string instead. Additionally, there is a custom formatter option available to allow you to change the input unit to one of your choice, e.g.: if the input unit is bits, you are able to switch and display the unit as bytes, correctly formatted. The formatted value is applied in the tooltip. The use cases below outline each of these scenarios.

CodeSandbox

Download data as CSV

The TreeMap component supports download data in CSV format using a toolbar button. To enable this feature, a ChartToolbar subcomponent with ChartToolbar.DownloadData inside of it must be provided to the TreeMap component. On click of the download button, raw data will be downloaded as a CSV file.

The CSV file contains the following columns:

• name - the name of the node
• value - the value of the node
• parent - the parent of the node

CodeSandbox

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

CodeSandbox

Label Display

The TreeMap component offers a labelsDisplay prop to control how labels are presented.

When labelsDisplay is set to cluster, labels will appear above each group of nodes, indicating the name of the parent cluster. When labelDisplay is set to nodes, labels will be displayed within each node, showing the name of the individual child node.

These options can be combined by setting the labelDisplay prop to all. In this mode, both parent cluster names and individual child node names will be displayed simultaneously.

CodeSandbox

Colors

The TreeMap component provides a set of predefined color palettes that can be used out of the box to provide more appealing visualisations. See Charts Colors for more info.

CodeSandbox

Error state

The ErrorState subcomponent is responsible for handling errors in a graceful manner, ultimately improving the overall user experience. Its primary function is to catch any errors that may occur with the data and display a fallback UI instead of crashing the entire application. The fallback UI occupies the full width and height of the chart, ensuring that users are still provided with a meaningful interface even in the presence of errors.

CodeSandbox

The ErrorState subcomponent offers a versatile feature that enables it to handle both default and custom error messages. You can provide a custom message through the ErrorState subcomponent, which will then override the default error message. This flexibility allows developers to tailor error messages to their specific needs and requirements, ensuring a more personalized and informative user experience.

CodeSandbox

The ErrorState subcomponent provides the flexibility to format custom error messages using HTML, which allows for enhanced customization and adaptability in presenting error information. Furthermore, it is possible to incorporate the original thrown error within your custom error message, ensuring that users receive comprehensive and relevant information when an error occurs.

CodeSandbox

CodeSandbox

EmptyState

The EmptyState subcomponent serves as a fallback when there is no data available to display in a chart. Its purpose is to provide a user-friendly way of informing the user about the current situation. When there is no data, a fallback UI is displayed occupying the full width and height of the chart, along with a default message.

CodeSandbox

A feature of EmptyState is its ability to handle custom messages. It provides the flexibility to format custom messages using HTML, which allows for enhanced customization and adaptability in presenting error information.

CodeSandbox

CodeSandbox

Loading

The loading prop is a boolean value that can be passed to the TreeMap component to control its loading state. When the loading prop is set to true, the loading indicator appears in the middle of the chart plot to inform the user that the component is currently fetching or processing data. When the loading prop is set to false, the component should display its regular content.

CodeSandbox

CodeSandbox

Styling

The TreeMap also accepts custom styling, which could be set using the props className and/or style, as a regular html element

CodeSandbox