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. Currently, it supports two variants used
for creating the chart: RectSeries and
DotSeries
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.
Learn more about the data format here.
Data accessors
Accessors specify how to retrieve data from your data structure. Accessor strings that contain dots allow you to retrieve nested data. If the actual property key contains a dot, you can escape an accessor by enclosing the string in square brackets.
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, log,
timeorcategorical, as well as the positionto indicate where the axis should be placed, which can bebottom, top, leftorright`.
You can add as many axes as needed to the chart but only the first axis of each
position will be visually displayed.
Mirrored Axes
There is an additional position option called both for displaying a mirrored
axis for either the XYChart.XAxis or the XYChart.YAxis.
Axis label
The label property can be used to include a text label for a given axis. If
set, it will also be shown in the tooltip identifying the corresponding data.
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.
Multiple axes
When using any XYChart up to four different axes can be visually displayed at
the same time.
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.
Chart Interactions
The XYChart provides various interactions (e.g. zoom-x, zoom in, zoom out, and
pan) that are enabled all by default. See
chart interactions for more details.
Zoom and Pan
Every X-axis can opt-in or out of having the zoom and pan enabled. This also
applies regardless of the position (top, bottom). To disable these interactions,
disableZoom and disablePan can be specified as props for the XAxis
subcomponent.
As soon as there's one X-axis with zoom, the controls and interactions are enabled. When performing any zoom interaction, it affects to all the X-axis with also zoom enabled.
Categorical axis are excluded and will never be zoomed or panned.
onZoomChange
Users can subscribe to changes on interactions made on X-axis in the XYChart
by specifying a callback onZoomChange for the XAxis subcomponent. See
chart interactions to know all possibilities.
Infinite Zoom
The infinite zoom provides a way to zoom and pan without limits. This way, the boundaries set by the current domain will be bypassed.
If the customer enables the feature and exceeds the data domain, the chart won't show any data unless the consumer provides new ones for the new domain.
This feature can be enabled by defining infiniteZoom prop for the desired
XAxis subcomponent.
Initial and Current zoom
A chart's domain is determined by its data, and each axis can define its scale
boundaries by a min and max property as explained
here. However, there's a way to set the
initialZoom (min, max) of the chart by setting this property on the desired
XAxis subcomponent. This will cause the chart to display plot information at
this initial specified domain, no matter the dataset used. There's another
property called currentZoom (min, max) that can also be combined with the
initialZoom to perform other more advanced actions, like synchronized zoom
between Charts.
The priority in which these properties are being considered for plotting the information on the chart is the following:
currentZoom(Highest priority)initialZoom- Custom min/max on axis
- Domain derived from data (Lowest priority)
Toolbar
The toolbar is one of the ways to visually interact with the chart. In the
XYChart, it's displayed by default, but in order to customize it, a
XYChart.Toolbar subcomponent must be added. This subcomponent supports
hidden, draggable, placement and collapsed props.
Download data as CSV
The XYChart component supports download data in CSV format using a toolbar
button; this is enabled by default in the toolbar.
Each series that derives from XYChart have their own accessors. There are
accessors with the same names and accessors exclusive to a variant. When
downloading the data in a CSV, the columns will be the series followed by all
the accessors of all series variants, even if they are not included in the chart
itself.
The values of accessors in series that are not used in are null.
The accessors and their meanings are:
series- the type and number of the series.x0- the value corresponding to the data from the x0 accessor.x1- the value corresponding to the data from the x1 accessor.y0- the value corresponding to the data from the y0 accessor.y1- the value corresponding to the data from the y1 accessor.value-Rect exclusive- the value corresponding to the data from the valueAccessor.
It's also possible to programmatically trigger the download of the CSV file via
the downloadData function in the XYChartRef.
Intent options
The XYChart supports intent options in the toolbar. The intents appear in the
toolbar's dropdown menu, allowing users to perform actions such as sharing a
chart or viewing data in another application.
To add intent options to a XYChart, use the XYChart.Intent subcomponent:
Intent properties
payload: An object containing the data to be passed to the target app. The structure depends on the target application's requirements.options: Configuration options for the intent.keyProperties: Array of properties that should be included as keys in the intent.recommendedAppId: Suggested target application ID.recommendedIntentId: Suggested intent ID.responseProperties: Array of properties to be included in the response.icon: Optional custom icon to be displayed next to the intent option.onResponse: Optional callback function that is called when a response is received from the target app.
Examples
The following examples demonstrates different intent options in XYChart:
Styling
The XYChart also accepts custom styling, which can be set using the properties
className and style as in a regular html element.
Thresholds
Thresholds are used to mark meaningful ranges or values, and they can add contextual information to axes of type numerical (log and linear) and time.
Thresholds may represent either a single point or a range, and can be defined as
static or dynamic. In order to link the threshold to a specific axis, a valid
yAxisId property must be set, as well as an additional xAxisId property if
the threshold is of type dynamic.
Customization of thresholds is possible through additional properties such as
color, label and strokeOnly (only for ranges). The label property can be
used to display a label for the threshold, which will be shown in the tooltip
when hovering over the threshold. The color property allows you to set a
custom color for the threshold line, while the strokeOnly property will modify
the display of the range threshold to show only the stroke without filling the
area.
Point and Range
Both point and range thresholds can be represented by static or dynamic data sources. A static data source has a single value representing a point or a single key-value pair representing a fixed range. A dynamic data source has a data array containing more than one value or various key-value pairs.