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.
Import
import { TreeMap } from '@dynatrace/strato-components-preview/charts';
Use cases
The TreeMap component expects a structured tree object containing hierarchical
data, where each cluster may have children and where two levels of categories
are supported, i.e. parent & child.
The categories should provide a name and a value which will be displayed in the tooltip and the legend.
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.
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.
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.
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.
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 nodevalue- the value of the nodeparent- the parent of the node
It's also possible to programmatically trigger the download of the CSV file by
calling the downloadData method on the TreeMap instance reference.
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.
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.
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.
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.
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.
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.
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.
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.
Styling
The TreeMap also accepts custom styling, which could be set using the props
className and/or style, as a regular html element