XYChart
The XYChart
encompasses various types of charts that utilize both x-axis and
y-axis for data representation, designed to visually display and analyze data
that involve two numerical variables.
Import
import { XYChart } from '@dynatrace/strato-components-preview/charts';
Use cases
The XYChart
encompasses various types of charts that utilize both x-axis and
y-axis for data representation, designed to visually display and analyze data
that involve two numerical variables. Presently, it supports the Heatmap chart
type.
Data
The data provided to the XYChart
component via the data
property will be
used in combination with the accessors of each series.
The series subcomponent has an optional data
property that can be used to
provide specific data for that series.
Truncation mode
The purpose of truncation is to gracefully handle extra long labels within data
visualization components. By changing the value of the truncationMode
property, you have control over where truncation is applied within charts. By
default, the truncation is applied to the middle of labels with the use of an
ellipsis. Truncation can, however, be changed to instead be applied at the start
or end of data visualization component labels.
Coloring
The XYChart
's colorPalette
property supports predefined color palettes,
custom color palettes, as well as custom color ranges. See
coloring for more details.
Custom color palettes
The custom color palettes can be useful to apply to data of type string.
Custom color ranges
The custom color ranges can be useful to apply to data of type number.
Size
By default, the chart will use all the available space up to a maximum height of
300 pixels and a width of 100% of the container. This maximum height and width
can be changed by providing a value in the height
and width
properties of
the XYChart
.
Axes
To display a series in the plot, it is necessary to include both XYChart.XAxis
and XYChart.YAxis
subcomponents, which will require an id
property that
matches the xAxisId
and yAxisId
used in a given series.
You will also need to define the type
property, used to determine the axis
scale type, which can be numerical
, time
or categorical
, as well as the
position
to indicate where the axis should be placed, which can be bottom
,
left
or right
. You can add as many axes as needed to the chart but only the
first axis of each position will be visually displayed.
Mirrored Y-axes
There is an additional position option for the XYChart.YAxis
named both
that
when used will display a mirrored y-axis.
Axis label
The label
property can be used to include a text label for a given axis.
Reversed Axis
The reversed
property inverts the scale on the chosen axis.
Axis visibility
The hidden
property can be used to visually hide the axis.
Axis layout and size
The tickLabelLayout
property gives you the option to choose between a
horizontal
(default) or vertical
layout for the axis tick values.
The tickLabelMaxSize
TBD.
Axis min and max
The min
and max
properties define the axis boundaries. By default, the
auto
setting is applied to both min
and max
properties, which
automatically calculates the axis scale's minimum and maximum values from the
chart data, akin to data-min
and data-max
, and establishes the baseline of
the Y-axis at zero. A custom number or date can also be provided to set custom
axis boundaries.
Axis unit and formatter
With the unit
property you can provide a unit that will be displayed along the
data in the chart. The formatter
will allow you to format data of type date or
number.
Legend
The purpose of the legend is to provide additional identifying information for the chart, without needing to interact with the legend directly. If there are multiple series in the chart, only the first series will be reflected on the legend.
Visibility
The legend of the XYChart
will be displayed by default, but can be optionally
hidden by setting the hidden
property to true on the XYChart.Legend
subcomponent.
Position
By default, the position of the legend of the XYChart
is set automatically 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.
Empty state
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.
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.
Loading state
The loading
property is a boolean value that can be passed to the XYChart
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.
Download data as CSV
The XYChart
component supports the download of data in CSV format via the
downloadData
function in the XYChartRef
.
Styling
The XYChart
also accepts custom styling, which can be set using the properties
className
and style
as in a regular html element.