BarSeries

The BarSeries renders rectangular bars to visualize values across categories, numbers or time. It supports simple, grouped (clustered), and stacked layouts, making it ideal for comparisons, totals, and distributions. The BarSeries works with numeric, time, and categorical axes, and handles a wide range of data types—perfect for Bar, Column, and Stacked charts.

OverviewProperties

Import

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

Overview

To better understand the accessor patterns, here are some common terms used in this documentation:

• Primary Accessor: Defines the bar's position along the main axis (e.g., x0Accessor for vertical bars).
• Growth Accessor: Defines the bar's length or height (e.g., y1Accessor for vertical bars).
• Primary Axis: The axis associated with the primary accessor.
• Growth Axis: The axis associated with the growth accessor.
• Base Bucket: A discrete slot or category on the primary axis where one or more bars are drawn. For a categorical axis, each category is a bucket.

A Bar series displays values as rectangular bars spreading from a configurable base X or Y axis. It supports three variants: single, stacked, and grouped, and works with categorical, numerical, time, and log axes.

• Single: one bar per base bucket, shown as a vertical or horizontal bar.
• Stacked: bars from multiple series accumulate along the growth axis. Supported only when the growth accessor is numerical, time, or log.
• Grouped: multiple series appear side-by-side within each base bucket for direct comparison. Supported only when the primary accessor is categorical.
• Range bars: a bar that spans between two values. Available in the grouped and single variants.
• Full rectangles: manual placement using four accessors (x0Accessor, x1Accessor, y0Accessor, y1Accessor) to draw arbitrary rectangles; useful for waterfall-like layouts (single variant only).

Usage

Add XYChart.BarSeries inside XYChart. Provide accessors to describe the bar’s position (primary accessor) and growth (growth accessor). Orientation is inferred from the accessor pattern, no orientation prop required.

Required accessors depend on the pattern:

• Vertical single bars: x0Accessor (position) + y1Accessor (height)
• Horizontal single bars: y0Accessor (position) + x1Accessor (width)
• Vertical floating bars: x0Accessor + y0Accessor + y1Accessor
• Horizontal floating bars: y0Accessor + x0Accessor + x1Accessor
• Vertical range bars: x0Accessor + x1Accessor + y1Accessor
• Horizontal range bars: y0Accessor + y1Accessor + x1Accessor
• Full rectangle (manual placement): x0Accessor + x1Accessor + y0Accessor + y1Accessor (single variant only)

Additionally:

• seriesIdAccessor: groups datapoints into series (enables multiple series in one BarSeries slot)
• nameAccessor: series label for legends and tooltips

Assign the series to axes via xAxisId and yAxisId. See XYChart docs for axis configuration.

Variants

Single

This type refers to independent bars, which support all valid accessor patterns. Specific details for the accessors structure can be found below:

• Automatic direction:
  • Vertical bars: x0Accessor + y1Accessor
  • Horizontal bars: y0Accessor + x1Accessor
• Waterfall-like rectangles:
  • Use variant="single" with x0Accessor + x1Accessor + y0Accessor + y1Accessor to manually position rectangles. Stacking and grouping are not supported for full rectangles.
• Note:
  • Multiple floating range bars per category can overlap in variant="single". Use variant="group" with x0Accessor + y0Accessor + y1Accessor to show them side-by-side.

Examples:

Stack

Data can be displayed stacked by setting the BarSeries variant to stack. Bars stack at the same primary accessor by using the seriesIdAccessor to group the data. Stack behaviour is supported for all axes except categorical-type if they belong to a growth axis.

These accessors patterns are valid for stacking:

• Vertical stacked bars: x0Accessor + y1Accessor
• Horizontal stacked bars: y0Accessor + x1Accessor
• Stacked bars with X-range span: x0Accessor + x1Accessor + y1Accessor (stacks vertically, grouped by the X range)
• Stacked bars with Y-range span: y0Accessor + y1Accessor + x1Accessor (stacks horizontally, grouped by the Y range)

The following accessor patterns are not supported for stacking:

• Floating range bars (Y-range only: y0Accessor + y1Accessor)
• Full rectangles (x0Accessor + x1Accessor + y0Accessor + y1Accessor)

Examples:

Group

Data can also be displayed grouped by setting the BarSeries variant to group, where the bars will be positioned side-by-side within the same bucket. In order to group, a categorical primary axis is required (the axis used for x0Accessor in vertical bars or y0Accessor in horizontal bars). If the primary axis is numerical, time, or log (i.e., not categorical), the series will fall back to variant="single".

These accessors patterns are valid for grouping:

• Vertical grouped bars: x0Accessor + y1Accessor
• Vertical grouped range bars: x0Accessor + y0Accessor + y1Accessor
• Horizontal grouped bars: y0Accessor + x1Accessor
• Horizontal grouped range bars: y0Accessor + x0Accessor + x1Accessor

The following accessor patterns are not supported for grouping:

• X-range with growth (x0Accessor + x1Accessor + y1Accessor)
• Y-range with growth (y0Accessor + y1Accessor + x1Accessor)
• Full rectangles (x0Accessor + x1Accessor + y0Accessor + y1Accessor)

Examples:

Axis compatibility

The display behavior of BarSeries variants is tightly coupled with the axis types they are assigned to. To ensure the chart displays as expected, please note the following requirements:

• Grouping requires a categorical primary axis (e.g., categorical X-axis for vertical bars).
• Stacking works with numerical, time, and log axes. A categorical growth axis cannot stack.
• Unsupported combinations automatically fall back to supported behavior, typically variant="single", and log a warning.

Data

The data provided to the BarSeries component via the data property will be used in combination with the accessors of each series.

Coloring

By using the color and colorPalette properties in the BarSeries you can overwrite the coloring from the XYChart component. These two properties are mutually exclusive. For more information about how to use coloring in the chart you can refer to the XYChart docs.

The XYChart.BarSeries subcomponent supports functions for the color and colorPalette props to customize coloring per series in case more than one series is presented in the same slot.

Color rules

ColorRules are advanced coloring tools for the chart, allowing you to apply conditional coloring based on data values. See more details in the XYChart docs.

Series actions

A series action is a creator, defined interaction with a given data point in the chart. Basic interactions include copying a series name and inspecting the underlying data of a data point. Series actions support both synchronous and asynchronous callbacks. In order to enable chart interactions, the ChartSeriesAction subcomponent needs to be appended within the XYChart. 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. Intents could be added as part of the series action as well with ChartSeriesAction.Intent.

If the datapoint belongs to a stack or group that belongs to a categorical primary axis, the datapoint together with the other datapoints in the same stack or group will be returned to be used in the action.

Custom tooltip

Pass a callback function as the XYChart.Tooltip slot children to take full control over what is displayed when a data point is hovered. The callback receives a payload object whose barPayload key is set when a BarSeries point is active. barPayload exposes:

• seriesName — the name of the hovered series.
• color — the resolved color of the series.
• datapoint — the original data record (with accessor values such as x0, y0, etc.).

Return any JSX to show a custom tooltip, null to hide it for a specific series, or undefined to fall back to the default tooltip. You can also set hidden on XYChart.Tooltip to suppress the tooltip entirely.

Value representation

Relative values indicate the proportion that a given dimension contributes to the sum (100%) of a given bar. The valueRepresentation prop can be used to change this behavior.

• For series with only a single dimension, the relative value is based on the maximum value within the given series.

• For series with stacked bars, each bar will scale relative to itself, meaning the total height of the stack will be 100%. In case of having positive and negative values in the same stack, the positive and negative values will be scaled together, where the 100% will be the highest absolute value amongst the two positive and negative parts of it. This allows for easy comparison of the relative contribution of each dimension within the stack, regardless of the difference amongst absolute values.

• For series with grouped bars, each bar will scale relative to the total addition of all bars within the same category, allowing for easy comparison of the relative contribution of each bar within the category regardless of the difference amongst absolute values. In case of having positive and negative values in the same category, the positive and negative values will be scaled together, where the 100% will be the highest absolute addition of bars amongst the two positive and negative parts of it. This allows for easy comparison of the relative contribution of each bar within the category, regardless of the difference amongst absolute values.

Top-list configuration

It is possible to display a top-list visualization using XYChart.BarSeries with the labelAccessor prop. The standalone TopList component builds this layout automatically; use XYChart.BarSeries directly when you need full control over axis configuration, coloring rules, or layout direction.

To set it up, add variant="single" to XYChart.BarSeries and provide labelAccessor for the in-bar text. For the default horizontal layout, use y0Accessor (category) and x1Accessor (numerical value).

When all records share the same seriesIdAccessor value the chart displays as a single series. When each record has a unique value, each bar becomes its own series—each with its own color and legend entry.

Important: always add hidden to the numerical axis, as axis tick numbers can be redundant and distracting.

The formatter on the categorical axis receives the raw category string and the full data record. Use it to display a derived value—such as the numerical metric—as the axis tick label instead of the raw category key.

Layout configurations

The labelAccessor works with all four bar orientations that XYChart.BarSeries supports. Switch orientation by choosing the accessor pattern and adjusting the axes types and positions accordingly.

Orientation	Accessors	Axis to hide
Horizontal LTR (default)	y0Accessor + x1Accessor	XYChart.XAxis (numerical)
Horizontal RTL	y0Accessor + x1Accessor + reversed on X axis	XYChart.XAxis (numerical)
Vertical BTT	x0Accessor + y1Accessor	XYChart.YAxis (numerical)
Vertical TTB	x0Accessor + y1Accessor + reversed on Y axis	XYChart.YAxis (numerical)

For the RTL horizontal layout, pass reversed on the numerical XYChart.XAxis and move the categorical XYChart.YAxis to position="right". The bars grow from right to left and the labels remain inside the bars.

For the TTB vertical layout, pass reversed on the numerical XYChart.YAxis and move the categorical XYChart.XAxis to position="top". The bars grow from top to bottom.

In both reversed cases you must still set hidden on the numerical axis—the reversed prop only controls direction, not visibility.

Tooltip behavior with labelAccessor

The tooltip adapts its display depending on whether a legend is visible:

• Legend visible (default): the labelAccessor value is shown as the tooltip header.
• Legend hidden: the labelAccessor value is shown under the series section in the tooltip body.

To hide the legend, add <XYChart.Legend hidden /> inside the chart. When no legend is visible, the label moves into the tooltip body automatically.