--- title: "Perspective - Bar" description: "A foundational comparison chart that plots one or more series of data as vertical columns against a category axis." --- # Perspective - Bar > A foundational comparison chart that plots one or more series of data as vertical columns against a category axis. ![The default Perspective Bar Chart component.](imgs/bar-chart-default.png) **Component Palette Icon:** ![The Bar Chart component icon shown in the Perspective Components panel and Project Browser.](imgs/bar-chart-icon.png) The Bar component is a foundational comparison chart that plots one or more series of data as vertical columns against a category axis. The Bar component has four pre-configured variants: * **Vertical**: Bars drawn as vertical columns growing up from the category axis. This orientation is well-suited to comparing values across a small number of short category labels. This variant is the default orientation. * **Horizontal**: Bars drawn as horizontal rows growing right from the category axis. This orientation is well-suited to ranked comparisons and long category labels that would not fit within a vertical column. * **Stacked**: A multi-series chart where series sharing a category are stacked into a single bar per category, with the combined height representing the total. * **Diverging**: A horizontal chart where series diverged from a shared baseline. Positive values extend in one direction, while negative values extend in the other. This variant is useful for comparing two opposing measures per category. ## Properties Most Properties have binding options. For more information on bindings, see [Types of Bindings in Perspective](ignition-modules\perspective\working-with-perspective-components\bindings-in-perspective\bindings-in-perspective.md). This section only documents the `props` category of properties. The other categories are described on the [Perspective Component Properties](ignition-modules\perspective\working-with-perspective-components\perspective-component-properties.md) page. |Name|Description|Property Type| |---|---|---| |data| The data source objects used to populate the chart. Each row represents a `category`, and the populated series reads the corresponding `value` from a named field on that row. | object| |series| The series configuration per entry of bars. Options include:**label**: Name shown in the legend and the tooltip. Value is string.**value**: The field from the data rows that set each bar's length. Value is string. **category**: The field from the data rows that label the categories. Value is string.**dataLabels**: The value label shown at each bar. Refer to the [dataLabels](#seriesxdatalabels-properties) property table for more details. **visible**: Shows or hides the series. Hidden series data is not deleted. Value is boolean.**advanced**: Advanced settings to configure when applicable, including: **yAxis**: Sets the y-axis entry this series is measured against when using dual-axis layouts. Value is numeric.**tooltips**: Tooltip settings specifc to this series. This property can only be applied if `tooltip.trigger` is set to `item`. Individual setting descriptions match those described for the top-level `tooltip` property, and will override any configurations if set here.|object| |stackGroups| Series in the same group stack into one bar per category, with an optional label for the total. Leave empty to draw every series as its own bar. Bars stack in the order the series are declared, not the order listed here. See the [stackGroups](#stackgroups-properties) property table for more details.|object| |xAxis|The x-axis configuration settings. On a vertical chart this is the category axis, while on a horizontal chart it is the value axis. Options include: **visible**: Shows or hides the x-axis. Value is boolean.**position**: Determines if the x-axis sits on the `top` or `bottom` edge. Value is string.**min**: The lowest value the axis shows. A value of `auto` will fit all data. This property is ignored if this is the category axis. Value is numeric or string.**max**: The highest value the axis shows. A value of `auto` will fit all data. This property is ignored if this is the category axis. Value is numeric or string.**boundaryGap**: Spacing at the two ends of the axis. On the category axis, `true` insets the bars so they sit inside their category bands. On the value axis, `true` enables padding below the lowest value and above the highest based on the `appearance.barGap` property. Value is boolean.**gridLines**: Displays vertical grid lines across the plot area when true. Value is boolean.**axisLine**: Displays a line along the axis when true. Value is boolean. **ticks**: The tick mark configuration along the axis.**visible**: Shows or hides the tick marks. Default is true. Value is boolean.**displayInside**: Draws the tick marks on the inside of the axis line, facing the plot area. Default is false. Value is boolean.**majorSplit**: Number of intervals to divide the value axis into. The actual amount may differ to keep numbers readable. A value of `auto` will fit all data. This property is ignored if this is the category axis. Value is numeric or string.**minorSplit**: Number of minor ticks to place between each pair of major ticks. A value of `0` will hide them. This property is ignored if this is the category axis. Value is numeric.**label**: The tick label and axis name configuration. **visible**: Shows the tick label when true. Value is boolean.**name**: The name of the axis, displayed alongside it. Value is string.**color**: The color of the x-axis label text. Overrides `elementStyle.color` when both are set.**fontSize**: The font size of the x-axis label text. Value is numeric.**elementStyle**: Text style for a label rendered onto a chart canvas, including typography, alignment, box styling, and shadow.**advanced**: Contains the `axisPointer` configuration specific to the x-axis. Only applicable to the category axis, unless the `axisPointer.type` is `cross`, which then adds an axis pointer to the value axis as well. These configuration options match the description of the top-level `axisPointer` property. Note that disabling the top-level property will also disable this property. | object| |yAxis| The y-axis configuration, where each array element applies to each y-axis. The default array is the primary axis. More axes can be added for dual-axis layouts. On a horizontal chart the y-axis is the category axis. Options include: **visible**: Shows or hides the y-axis. Value is boolean.**min**: The lowest value the axis shows. A value of `auto` will fit all data. This property is ignored if this is the category axis. Value is numeric or string.**max**: The highest value the axis shows. A value of `auto` will fit all data. This property is ignored if this is the category axis. Value is numeric or string.**boundaryGap**: Spacing at the two ends of the axis. On the category axis, `true` insets the bars so they sit inside their category bands. On the value axis, `true` enables padding below the lowest value and above the highest based on the `appearance.barGap` property. Value is boolean.**gridLines**: Displays vertical grid lines across the plot area when true. Value is boolean.**axisLine**: Displays a line along the axis when true. Value is boolean.**ticks**: The tick mark configuration along the axis.**visible**: Shows or hides the tick marks. Default is true. Value is boolean.**displayInside**: Draws the tick marks on the inside of the axis line, facing the plot area. Default is false. Value is boolean.**majorSplit**: Number of intervals to divide the value axis into. The actual amount may differ to keep numbers readable. A value of `auto` will fit all data. This property is ignored if this is the category axis. Value is numeric or string.**minorSplit**: Number of minor ticks to place between each pair of major ticks. A value of `0` will hide them. This property is ignored if this is the category axis. Value is numeric.**label**: The tick label and axis name configuration. **visible**: Shows the tick label when true. Value is boolean.**name**: The name of the axis, displayed alongside it. Value is string.**color**: The color of the y-axis label text. Overrides `elementStyle.color` when both are set.**fontSize**: The font size of the y-axis label text. Value is numeric.**elementStyle**: Text style for a label rendered onto a chart canvas, including typography, alignment, box styling, and shadow.**advanced**: Contains the `axisPointer` configuration specific to the y-axis. Only applicable to the category axis, unless the `axisPointer.type` is `cross`, which then adds an axis pointer to the value axis as well. These configuration options match the description of the top-level `axisPointer` property. Note that disabling the top-level property will also disable this property. | object| |title| Chart title and subtitle configuration. **visible**: Shows the title text when true. Value is boolean.**text**: Main title text. Value is string.**color**: The color of the title text. Overrides `elementStyle.color` when both are set.**fontSize**: The font size of the main title text. Value is numeric.**subtitle**: Configures the subtitle under the title, including text, color, size, and style.**position**: Determines the title placement. Value is string.**gap**: Pixel gap between the main title and subtitle. Value is numeric.**elementStyle**: Text style for a label rendered onto a chart canvas, including typography, alignment, box styling, and shadow.|object| |legend| The legend configuration. **visible**: Shows the legend when true. Value is boolean.**position**: Determines the legend placement. Value is string.**orientation**: Determines whether the legend entries run across or down. Value is string.**interactive**: Whether clicking a legend entry shows or hides that series. Override the true/false entry with `single` to allow ones series at a time, or `multiple` to allow several. Value is string.**color**: The color of the legend text. Overrides `elementStyle.color` when both are set.**fontSize**: The font size of the legend text. Value is numeric.**elementStyle**: Text style for a label rendered onto a chart canvas, including typography, alignment, box styling, and shadow.|object| |zoom| Zoom and pan settings. Users can zoom along the x-axis, y-axis, or both. **enabled**: Enables zooming. Value is boolean. **type**: Determines how the zoom functions by selecting either a `slider` scrollbar, an `inside` scroll-wheel, or `both`. Value is string.**axis**: Sets the axis the zoom applies to. Value is string.**xPosition**: Determines if the x-axis slider sits on the `top` or `bottom` edge. Value is string.**yPosition**: Determines if the y-axis slider sits on the `right` or `left` edge. Value is string. **height**: Height of the x-axis slider in pizels. Applies when `axis` is `x` or `both`. Value is numeric.**width**: Width of the y-axis slider in pixel. Applies when `axis` is `y` or `both`. Value is numeric.**backgroundColor**: The background color of the slider track. Follows the light or dark theme when left empty. |object| |tooltip|The tooltip shown on hover. Any setting configured with `series.x.advanced.tooltip` will override this property. **visible**: Shows the tooltip when true. Value is boolen. **trigger**: Determines how the tooltip is shown, and the applicable `formatter` options. Selecting `axis` will show one tooltip for every series at the hovered category, while `item` will show a separate tooltip for the hovered bar. Value is string.**formatter**: Sets the tooltip display format. Options include: **type**: Sets the format type as either `value` or `template`, depending on whether the user wants to only customize the value display within the default tooltip format, or replace the default tooltip format entirely with a customized template. Value is string.**value/template**: Expression applied to each layout per the `format` type selected. The dropdown will display default options, but manual entries are accepted. Value is string. See the [tooltip Formatting Options](#tooltip-formatting-options) section for more examples on how to customize a tooltip.|object| |axisPointer|The band, line, or crosshair that follows the hovered category along the axes, and its label. **enabled**: Displays the pointer type on this axis when hovering over the chart. Value is boolean.**type**: Sets the pointer shape between `shadow`, `line`, `cross`, or `none`. Select none to hide any shape configuration and only show the label. Value is string.**label**: The label the pointer prints against the axis, highlighting the hovered category or value data.**visible**: Shows the pointer's label against the category axis. Note that both axes are shown when the pointer shape is `cross`. Value is boolean.**color**: The color of the legend text. Overrides `elementStyle.color` when both are set.**fontSize**: The font size of the legend text. Value is numeric.**elementStyle**: Text style for a label rendered onto a chart canvas, including typography, alignment, box styling, and shadow. |object| |appearance|Configures the chart theme and layout. **colorPalette**: Colors handed out, in order, to series that set no color of their own. **Orientation**: Swaps the category and value axes. Settings based on axis orientation will update automatically. Value is string.**sort**: Determines how the bars are ordered. See the [sort](#appearancesort-properties) property table for more details.**barGap**: Gap, as a percentage of bar width, between the bars of different series inside one category. Value is numeric.**barCategoryGap**: Gap, as a percentage of space for each category, between one category and the next. Value is numeric.**borderRadius**: Corner radius of the bars, in pixels. Value is numeric.**backgroundBar**: A faint full-length bar behind each value, showing how much of a scale it fills.**visible**: Shows the background bar. Value is boolean.**color**: Fill color of the background bar.**backgroundColor**: Background fill for the whole component.**animation**: Animation configuration for when the chart first renders and when data updates.**enabled**: Turns animation on. Value is boolean.**entry**: Animation for the initial chart render, including duration in milliseconds, easing curve selection, and delay pause in milliseconds. **transition**: Animation for each data change, including duration in milliseconds, easing curve selection, and delay pause in milliseconds.|object| |style|Sets a style for this chart. Full menu of [style options](appendix\reference-pages\style-reference.md) is available for text, background, margin and padding, border, shape and miscellaneous. You can also specify a [style class](ignition-modules\perspective\styles\style-classes\style-classes.md).|object| ### series.x.dataLabels Properties |Property|Description|Property Type| |---|---|----------| |visible|Shows or hides the value label at each bar. Default is false. | boolean| |position|Determines where the label sits relative to its bar. |string| |format|The label's text. Label text can include the following tokens, which refer to the corresponding bar data: `{series}``{value}``{category}``{dimension:}`, where `` can specify another field of the row. The text can incorporate any combination of these tokens, and be customized around them to include punctuation or units of measurement, as shown in some built-in defaults. |string| |color|The color of the data label text. Overrides `elementStyle.color` when both are set.|color| |fontSize| Font size of the data label text. Overrides `elementStyle.fontSize` when both are set.| numeric| |elementStyle|Text style for a label rendered onto a chart canvas, including typography, alignment, box styling, and shadow.|object| ### stackGroups Properties |Property|Description|Property Type| |---|---|----------| |series|Assigns the series that belong to a group, by label, or position in the series list. A series can only be assigned to a single group, so the first group that lists it will be where it belongs. Entries matching nothing are ignored, as are hidden series. A group with no series will not display any data. |object | |totalLabel|The label for the stack's total, displayed at the end of the bar. Each series keeps its own [data label](#seriesxdatalabels), so segments and totals can both be shown.**visible**: Shows or hides the stack's total label. With no format set, just the number is shown. Value is boolean.**format**: The label's text. Label text can include the following tokens, which refer to the corresponding bar data: `{sum}``{category}``{dimension:}`, where `` can specify another field of the row. The `{value}` and `{series}` tokens show nothing here as the total belongs to the stack rather than any one series. Leave blank to display the number of the total. Value is string.**color**: The color of the total label text. Overrides `elementStyle.color` when both are set.**fontSize**: Font size of the total label text. Overrides `elementStyle.fontSize` when both are set. Value is numeric.**elementStyle**: Text style for a label rendered onto a chart canvas, including typography, alignment, box styling, and shadow. | object| ### appearance.sort Properties |Property|Description|Property Type| |---|---|----------| |type| The order bars appear in along the category axis. Options include: **natural**: Maintains the order of the rows in `data`.**ascending**: Sorts by value, moving upward. **descending**: Sorts by value, moving downward. **live**: Sorts continuously as data updates for a racing-bar effect.| string| |field| The series values to sort by when there is more than one. Defaults to the first series. This property will be ignored when `type` is set to `natural` or `live`. |string| #### tooltip Formatting Options Tooltip display can be customized with the following built-in formatting properties and token options. Tokens serve as placeholders that will be replaced with live data during runtime. They are case-sensitve, include no spaces, and must be enclosed with curly braces. Index suffixes are accepted when entered as the series number following a colon. All tooltips will render using the en-US locale unless otherwise specified. When translated, text is processed as a whole phrase. Additionally, tooltips are HTML, so basic markup works within templates. However, the tooltip value expression is not HTML so `{value}` shows the value literally. The table below describes the available tokens that can be used, as well as some possible format examples. |Token|Description|Example Format|Example Output| |---|---|--------------|------------| |`{value}`| The y-axis value. When `value` is selected as the `format.type`, default dropdown options include `%`, `kW`, and `°F`. However, any unit can be entered before or after `{value}` by typing directly into the field for either type selection.|
`${value}`
|![](imgs/value.png)| |`{marker}`| Displays the `series[].color` selection as an identifying marker dot. Available for `template` types only.|
`{marker}{series}: {value}%`
|![](imgs/marker-series-value.png)| |`{series}`| Displays the `series[].label` text. Available under `template` types only.|
`{series}: {value}`
|![](imgs/bold-series.png)| |`{category}`|Displays the x-axis value. Available under `template` types only. |
`{category} — {marker}{series}: {value}`
|![](imgs/category.png)| |`{sum}`| Displays the total y-axis value for all series data sharing an x-axis category. Available under `template` types for stacked and diverging variants only. |
`{category} - {series:0}: {value:0}
``{category} - {series:1}: {value:1}` `{category}: {sum}`
|![](imgs/sum-proof.png)![](imgs/sum.png)| ## Script and Event Configuration The Bar component also has Component Events associated with it. See the [Perspective - Bar Scripting](perspective-bar-scripting.md) page for more information. ## Basic Bar Chart Example This example uses the default data for the vertical chart variant. Slight configuration changes were made to use the `datalabels`, the `axisPointer`, and `sort` properties to improve chart readability at a glance. The sample values used in this example are listed below in JSON format. ![A default Bar chart, sorted in ascending order, with visible data labels and a shadow shape axis pointer hovering over Line C.](imgs/vertical-bar-example.png) ```JSON title="Basic Bar Chart Sample Data" { "series": [ { "dataLabels": { "visible": true, "format": "{category}: {value}", }, } ], "axisPointer": { "type": shadow }, "appearance": { "sort": { "type": "ascending" } } } ``` ## Stacked Bar Chart Example The following example uses the default data for the stacked chart variant. Configuration changes were made to add more context to the chart, including a title and updated legend placement. The `zoom` property was also enabled so that the slider type could be used to view only the Wednesday and Thursday bar data. The sample values used in this example are listed below in JSON format. ![A stacked variant Bar chart, zoomed in to show just the Wednesday and Thursday bars.](imgs/stacked-bar-example.png) ```JSON title="Stacked Bar Chart Sample Data" [ { "xAxis": { "label": { "color": "#9DBAA3" } }, "yAxis": { "gridLines": { "visible": true } }, "title": { "text": "Time Spent on Maintenance" }, "legend": { "position": "top-right" }, "zoom": { "enabled": true, "type": "slider", "yPosition": "left", "backgroundColor": "#A4A4A4" } } ] ```