CategoricalBarChart
The CategoricalBarChart visually displays the frequencies or values of
distinct categories using rectangular bars. Each bar's length or height
corresponds to the quantity or value associated with a specific category, making
it easy to compare the relative differences among categories.
Import
import { CategoricalBarChart } from '@dynatrace/strato-components-preview/charts';
Use cases
The CategoricalBarChart expects an array of categories with a value and an
optional unit. The specified value can either be a number or a key-value pair.
In order to render a single bar for each category, specify a number as the
value. When a record is specified as a key-value pair, each pair will render a
bar within a group in the parent category. The key is used as the name of the
dimension for that bar.
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 CategoricalBarChart. If a number is passed to this
prop without any unit specified, it will be treated as px.
Change the layout
The layout prop specifies how bars are drawn within the chart. The horizontal
value renders the bar horizontally and the vertical option vertically. By
default, the bars are displayed in a vertical layout.
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. In order to enable chart interactions, the
ChartSeriesAction subcomponent needs to be appended within the
CategoricalBarChart. More subcomponents can be added within this component,
for instance the ChartSeriesAction.Item, where custom logic can be applied.
Change the group mode
When having multiple dimensions for each category, groupMode determines how
those dimensions are grouped. The stacked option stacks bars on top of each
other, whereas the grouped option displays them sequentially (next to one
another). Stacked bars are recommended when the relationship between dimensions
and their contribution to the total matters. Grouped bars are useful for
comparing values between dimensions and categories. This option doesn't have any
effect when there's a single value per category. By default, bars are stacked.
Change the chart color/s
The CategoricalBarChart provides a set of predefined color palettes and it
also accepts custom color palettes. See
coloring
for more details.
The CategoricalBarChart accepts a colorPaletteMode prop that can be set to
either single-color or multi-color, the first being the default setting and
meaning that all categories take the first color of an array, and the latter
meaning that the color is applied to the categories by index or by value.
Apart from all these options for providing a color palette, the
CategoricalBarChart also offers the ability to override colors for specific
series. When a color override is specified, it takes precedence over the color
that would otherwise be assigned from the color palette. However, it does not
affect the colors assigned to other series. This allows for fine-grained control
over the appearance of individual series within the chart. A color override is
done by category. We should specify the category name we want overridden and
provide the desired color to the CategoricalBarChart data using a color
prop.
Value representation
By default, values within a chart are displayed as is - with their absolute
value (e.g. 3.14 kB). However, this can be changed so that instead of absolute
values, relative values are used. Relative values indicate the proportion that a
given dimension contributes to the whole (100%) of the category. The
valueRepresentation prop can be used to change this behavior. In categories
with a single dimension, the relative value is always 100%.
Legend customization
The purpose of the legend is to provide additional identifying information for the chart without needing to interact with it directly.
Visibility
The legend for the CategoricalBarChart is shown by default in a chart with
more than one dimension per category, and otherwise it is hidden. In order to
hide or show the legend, you need to set the value of legend.hidden on the
subcomponent.
Legend position
By default, the legend of the CategoricalBarChart is positioned automatically
({position: "auto"}). This option prioritizes the legend placement to the
right of the chart area. When the chart width is reduced, the legend is
repositioned beneath the chart area. You can also 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.
Tooltip customization
Tooltips can be used to display additional detailed information about a selected
data point. A tooltip will be shown when hovering the chart at a certain
distance to a datapoint. The tooltip variant defines whether the tooltip
should contain data points from all the dimensions within a category (grouped)
or only the closest one (single). By default, the variant is single.
Truncation Mode
The purpose of truncation is to gracefully handle extra long labels within data
visualization components. By changing the value of this 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.
Axis customization
The category axis is defined as the axis containing the names of the chart's
categories. The value axis contains numeric values. Both will be positioned
either on the x- or y-axis, depending on the selected layout. When it's
horizontal, the category axis is the x-axis and the value axis is the y-axis,
and when it's vertical, vice versa.
Category axis
In the category axis, tick labels have a limited space, which depends on the
number of categories and the chart's width. If the tick label is larger than the
available space, it's truncated with ellipsis in the middle. tickLabelLayout
can be used to change the orientation of the tick labels to make better use of
the available space. The label prop can optionally be used to set the title
for the axis.
The maxSize prop defines the maximum growth in pixels of the axis. If the
maxSize value is bigger than the space that the axis has to display, the
maxSize value will be omitted.
Value axis
In the value axis, a min and max can be used in order to set the extents of
the chart. If no values are specified, these extents will be derived from the
data. When all the values are positive, the min is 0 and the max will be the
largest value. When all the values are negative, the min is the lowest value
and the max is 0. If there are mixed values, the min is the lowest value,
and the max is the highest value. The label prop can optionally be used to
set the title for the axis.
Formatter
As the CategoricalBarChart expects an array of categories 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
axis ticks, as well as in the tooltip and the axis magnifier. The use cases
below outline each of these scenarios.
Thresholds
Thresholds are used to mark meaningful ranges or values on a
CategoricalBarChart and they add contextual information to a numerical axis.
There are two variants of thresholds:
- a specific point represented on the value axis and a line across.
- a range - or filled area - represented by a pill on the value axis and a band across.
Point and Range
There is no limit defined for the number of threshold ranges or points that can
be used in a single CategoricalBarChart. The threshold will be positioned on
the left axis if the layout is vertical or on the bottom axis if the layout is
horizontal.
Points and Ranges on Vertical Layout
Points and Ranges on Horizontal Layout
There are three different types of threshold markers:
-
Range filled, where the value range is defined in order to display the threshold band. The stroke lines are not drawn unless the pill is hovered.
-
Range stroke-only variant, where a value range is defined in order to display the threshold band represented by dashed stroke lines. The stroke lines become continuous lines when the pill is hovered.
-
Point, where only one value is required to display the threshold. It's represented by a dashed line and when the point is hovered the line becomes a continuous line.
Stroke Only Ranges on Vertical Layout
Stroke Only Ranges on Horizontal Layout
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
CategoricalBarChart 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 CategoricalBarChart 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
CategoricalBarChart component. On click of the download button, raw data will
be downloaded as a CSV file.
The CSV file contains the following columns:
category- the name of the category (dimension)value- the value of the categorykey- the name of the second dimension (in case of multiple dimensions)
It's also possible to programmatically trigger the download of the CSV file by
calling the downloadData method on the CategoricalBarChart instance
reference.
Props
CategoricalBarChartProps
| Name | Type | Default | Description |
|---|---|---|---|
data | [] | - | Data object for the categorical bar chart |
height? | | | 300px | Chart height. When a number is specified, is considered as pixels, otherwise a valid height string is expected. |
width? | - | Chart width. A number in pixels is expected. Otherwise, it will take the full width of the container. | |
layout? | 'vertical' | Whether the bars are displayed in a 'vertical' or 'horizontal' layout. | |
groupMode? | 'stacked' | Strategy used for grouping the bars within a category. "stacked" will mount one on top of each other, and "grouped" will place one next to the other | |
colorPalette? | | | "categorical" | Color palette to be used for the bar category. |
valueRepresentation? | "absolute" | The way values are represented. "absolute" will display the value as it is, and "relative" displays a percentage value considering the other dimensions values within a category. | |
seriesActions? | (series: <, >) => | - | Category actions to be shown in the legend and tooltip actions |
truncationMode? | 'middle' | Truncation mode to use (start, middle, end) Applied to all the parts that truncate text. | |
colorPaletteMode? | "single-color" - each bar gets the same color | Mode in which bars are colored when single dimension data is shown | |
loading? | false | Show the loading indicator when truthy. |
CategoricalBarChart.Legend
To configure the legend, add CategoricalBarChart.Legend to the categorical bar
chart.
CategoricalBarChartLegendProps
Signature:
export declare type CategoricalBarChart = ;CategoricalBarChart.Tooltip
To configure the tooltip, add CategoricalBarChart.Tooltip to the categorical
bar chart.
CategoricalBarChartTooltipProps
| Name | Type | Default | Description |
|---|---|---|---|
variant | - | Tooltip variant. 'single' displays only the closest category, and 'grouped' all the category within a category. |
CategoricalBarChart.CategoryAxis
To configure the category axis, add CategoricalBarChart.CategoryAxis to the
categorical bar chart.
CategoricalBarChartCategoryAxisProps
| Name | Type | Default | Description |
|---|---|---|---|
tickLabelLayout? | 'horizontal' | Whether the tick labels are displayed in a 'vertical' or 'horizontal' layout. | |
label? | - | ||
maxSize? | - | Max size in pixels for the category axis. Size depends on the position this axis is assigned to – left axis will use width, bottom axis will use height. If there's no enough space for this maxSize, category axis will only take the available space for it. |
CategoricalBarChart.ValueAxis
To configure the value axis, add CategoricalBarChart.ValueAxis to the
categorical bar chart.
CategoricalBarChartValueAxisProps
| Name | Type | Default | Description |
|---|---|---|---|
label? | - | ||
min? | - | ||
max? | - | ||
formatter? | | <, > | - | Handler that is called for every tick value to be formatted. |
CategoricalBarChart.Threshold
CategoricalBarChart.Threshold provides a slot for defining annotations in the
chart.
CategoricalBarChartThresholdProps
| Name | Type | Default | Description |
|---|---|---|---|
data | - | The threshold data to be graphed by the component | |
color | - | The unique color picked in HEX, RGB, Color Token or HSL. | |
strokeOnly? | - | Whereas to show the ranges filled or only the strokes | |
label? | "Threshold" | Label to be shown in the threshold tooltip. |
CategoricalBarChart.EmptyState
CategoricalBarChart.EmptyState provides a slot where the Empty state wrapper
can be set.
EmptyStateProp
| Name | Type | Default | Description |
|---|---|---|---|
children | . | - |
CategoricalBarChart.ErrorState
CategoricalBarChart.ErrorState provides a slot where the Error state wrapper
can be set.
ErrorStateProps
| Name | Type | Default | Description |
|---|---|---|---|
children | . | ((errorMessage: ) => .) | - |