Skip to main content

    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.

    OverviewProperties

    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

    CodeSandbox

    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.

    CodeSandbox

    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.

    CodeSandbox

    Custom color palettes​

    The custom color palettes can be useful to apply to data of type string.

    CodeSandbox

    Custom color ranges​

    The custom color ranges can be useful to apply to data of type number.

    CodeSandbox

    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.

    CodeSandbox

    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.

    CodeSandbox

    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.

    CodeSandbox

    Reversed Axis​

    The reversed property inverts the scale on the chosen axis.

    CodeSandbox

    Axis visibility​

    The hidden property can be used to visually hide the axis.

    CodeSandbox

    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.

    CodeSandbox

    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.

    CodeSandbox

    Multiple axes​

    When using any XYChart up to four different axes can be visually displayed at the same time.

    CodeSandbox

    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.

    CodeSandbox

    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

    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.

    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

    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.

    CodeSandbox

    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.

    CodeSandbox

    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.
    CodeSandbox

    It's also possible to programmatically trigger the download of the CSV file via the downloadData function in the XYChartRef.

    CodeSandbox

    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:

    CodeSandbox

    Styling​

    The XYChart also accepts custom styling, which can be set using the properties className and style as in a regular html element.

    Annotations​

    Annotations are used to visualize specific events or contextual notes on the XYChart in the form of markers placed in time-based or numerical-based tracks.

    The marker represents an annotation at a certain point. They can be either a value (a certain time or number) or a range (from-to object), depending on the data provided to the Annotation. Annotations within the same timestamp/timeframe/number are grouped together under a single marker that displays the number of grouped annotations. Markers can be displayed on a single or multiple tracks. When there are more than three tracks, an overflow scroll is applied.

    Add annotations to the chart​

    In order to visualize annotation data inside the XYChart, a XYChart.Annotations component should be initialized. This component should have at least one track, that contains a marker component per annotation data point.

    The data provided to the XYChart.Annotations component via the data property is combined with the defined accessors to generate the corresponding tracks and markers. Also a mandatory xAxisId is required to match with the corresponding XYChart.XAxis, which can be either the bottom or the top one.

    The XYChartAnnotations.Track should have a unique track ID (trackIdAccessor) that will be used to match all the markers that belong to that specific track. Additional optional parameters include: labelAccessor, colorAccessor, symbol, indicatorDisplay and hidden.

    An annotation data point XYChartAnnotations.Marker should have a unique track ID (trackByAccessor) that will be used to match the track it belongs. Additional parameters include some which are mandatory startAccessor and endAccessor, and an optional symbol, titleAccessor, descriptionAccessor, colorAccessor and priority, which will be displayed in the tooltip.

    CodeSandbox

    Marker content​

    When the symbol is provided, it will become the marker content by default. When not, the data obtained through titleAccessor will be shown as marker content.

    In case the content of the marker is bigger than the size of the marker, it will expand to fit all the content inside, decoupling from the original scale. In these particular cases, it is encouraged to use the indicators, which will represent the real size of the bin.

    Visual customization​

    Tracks and markers support visual customization in order to differentiate various types of annotations.

    It's possible to set custom colors on both the track (to be applied to all markers) and the marker level by using the data obtained through colorAccessor property on the respective component. A marker's custom color has precedence over track's. This color can be set to any Design System color token, as well as any rgb, hex or CSS color.

    The symbol property allows you to apply an icon, emoji, single letter, glyph, or Design System icon to either an individual marker or to an entire track. When applied to a track, this symbol will be used as the default.

    When markers partially overlap one another, the order of the annotations defines which marker is displayed on top. Value annotations are always displayed above Range-based ones. It's also possible to customize the marker display order, by using the priority property. The higher the value of the priority property, the higher precedence the marker has. The priority property also affects the color of markers i.e. within a group, the color of the marker with the highest priority will be applied to the group.

    It's possible to assign a label to a track using the data obtained through labelAccessor property. Be aware that labels are hidden by default. To show a track's label, the showLabels property has to be applied to the XYChart.Annotations component.

    CodeSandbox

    Visibility​

    An entire track can be hidden by adding the hidden property to the XYChartAnnotations.Track component. The same configuration can be applied to a marker, by setting the hidden property on the XYChartAnnotations.Marker component.

    When hovering a marker (with the cursor), an annotation indicator appears over the chart area. The indicator's visibility can be customized on either a track or marker level by using the indicatorsDisplay property:

    • With the auto option, the default behaviour is applied - indicators appear on hover.
    • The always option sets indicators to always be visible within the chart area, regardless of the hovering behavior.
    • The never option sets indicators to never be visible.
    CodeSandbox

    Custom tooltip​

    The Annotations supports both default and custom tooltips for annotations. This allows creators to provide additional detailed information about specific datapoints or events in the chart.

    See Annotations Tooltip for more

    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​

    CodeSandbox

    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.

    Dynamic Thresholds​

    CodeSandbox

    Shared Crosshair​

    The shared crosshair feature allows users to synchronize the crosshair position across multiple XYChart or Timeseries instances. This is especially useful for comparing time-based data points across different charts.

    To enable crosshair synchronization, wrap the charts you want to synchronize with the SynchronizationProvider component.

    Important notes for XYChart:

    • x-axis Only: The shared crosshair synchronization only works for the X axis. y-axis are not supported.
    • Supported Axis: The shared crosshair will only synchronize on visible time axes. Numerical or categorical axes are not supported for crosshair synchronization.
    • Axis Priority: If both a bottom and a top time axis are present and visible, the bottom axis takes priority for synchronization.
    • Hidden Axes: Axes marked as hidden will not trigger or participate in crosshair synchronization, even if they are of type time.
    CodeSandbox

    Dot Shapes​

    The shape prop on XYChart.DotSeries allows you to display different geometric shapes for each data point in the series. In addition to the default circle, you can now choose between square, diamond, and triangle shapes.

    CodeSandbox
    Still have questions?
    Find answers in the Dynatrace Community