Skip to content

Latest commit

 

History

History
368 lines (297 loc) · 14.6 KB

bar.mdx

File metadata and controls

368 lines (297 loc) · 14.6 KB
Raw
title
Bar Chart

A bar chart provides a way of showing data values represented as vertical bars. It is sometimes used to show trend data, and the comparison of multiple data sets side by side.

import { useEffect } from 'react';

export const ExampleChart0 = () => { useEffect(() => { const cfg = { type: 'bar', data: { labels: [ 'January', 'February', 'March', 'April', 'May', 'June', 'July' ], datasets: [{ label: 'My First Dataset', data: [65, 59, 80, 81, 56, 55, 40], backgroundColor: [ 'rgba(255, 99, 132, 0.2)', 'rgba(255, 159, 64, 0.2)', 'rgba(255, 205, 86, 0.2)', 'rgba(75, 192, 192, 0.2)', 'rgba(54, 162, 235, 0.2)', 'rgba(153, 102, 255, 0.2)', 'rgba(201, 203, 207, 0.2)' ], borderColor: [ 'rgb(255, 99, 132)', 'rgb(255, 159, 64)', 'rgb(255, 205, 86)', 'rgb(75, 192, 192)', 'rgb(54, 162, 235)', 'rgb(153, 102, 255)', 'rgb(201, 203, 207)' ], borderWidth: 1 }] }, options: { scales: { y: { beginAtZero: true } } } }; const chart = new Chart(document.getElementById('chartjs-0').getContext('2d'), cfg); return () => chart.destroy(); }); return

; }

Example Usage

var myBarChart = new Chart(ctx, {
    type: 'bar',
    data: data,
    options: options
});

Dataset Properties

The bar chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset. For example, the color of the bars is generally set this way.

Name Type Scriptable Indexable Default
backgroundColor Color Yes Yes 'rgba(0, 0, 0, 0.1)'
base number Yes Yes
borderColor Color Yes Yes 'rgba(0, 0, 0, 0.1)'
borderSkipped string Yes Yes 'start'
borderWidth number|object Yes Yes 0
borderRadius number|object Yes Yes 0
clip number|object - - undefined
data object|object[]|number[]|string[] - - required
hoverBackgroundColor Color Yes Yes undefined
hoverBorderColor Color Yes Yes undefined
hoverBorderWidth number Yes Yes 1
hoverBorderRadius number Yes Yes 0
indexAxis string - - 'x'
label string - - ''
order number - - 0
pointStyle string|Image Yes - 'circle'
xAxisID string - - first x axis
yAxisID string - - first y axis

General

Name Description
base Base value for the bar in data units along the value axis. If not set, defaults to the value axis base value.
clip How to clip relative to chartArea. Positive value allows overflow, negative value clips that many pixels inside chartArea. 0 = clip at chartArea. Clipping can also be configured per side: clip: {left: 5, top: false, right: -2, bottom: 0}
indexAxis The base axis of the dataset. 'x' for vertical bars and 'y' for horizontal bars.
label The label for the dataset which appears in the legend and tooltips.
order The drawing order of dataset. Also affects order for stacking, tooltip, and legend.
xAxisID The ID of the x-axis to plot this dataset on.
yAxisID The ID of the y-axis to plot this dataset on.

Styling

The style of each bar can be controlled with the following properties:

Name Description
backgroundColor The bar background color.
borderColor The bar border color.
borderSkipped The edge to skip when drawing bar.
borderWidth The bar border width (in pixels).
borderRadius The bar border radius (in pixels).
pointStyle Style of the point for legend. more...

All these values, if undefined, fallback to the associated elements.bar.* options.

borderSkipped

This setting is used to avoid drawing the bar stroke at the base of the fill, or disable the border radius. In general, this does not need to be changed except when creating chart types that derive from a bar chart.

Note: for negative bars in a vertical chart, top and bottom are flipped. Same goes for left and right in a horizontal chart.

Options are:

  • 'start'
  • 'end'
  • 'bottom'
  • 'left'
  • 'top'
  • 'right'
  • false

borderWidth

If this value is a number, it is applied to all sides of the rectangle (left, top, right, bottom), except borderSkipped. If this value is an object, the left property defines the left border width. Similarly, the right, top, and bottom properties can also be specified. Omitted borders and borderSkipped are skipped.

borderRadius

If this value is a number, it is applied to all corners of the rectangle (topLeft, topRight, bottomLeft, bottomRight), except corners touching the borderSkipped. If this value is an object, the topLeft property defines the top-left corners border radius. Similarly, the topRight, bottomLeft, and bottomRight properties can also be specified. Omitted corners and those touching the borderSkipped are skipped. For example if the top border is skipped, the border radius for the corners topLeft and topRight will be skipped as well.

Interactions

The interaction with each bar can be controlled with the following properties:

Name Description
hoverBackgroundColor The bar background color when hovered.
hoverBorderColor The bar border color when hovered.
hoverBorderWidth The bar border width when hovered (in pixels).
hoverBorderRadius The bar border radius when hovered (in pixels).

All these values, if undefined, fallback to the associated elements.bar.* options.

Dataset Configuration

The bar chart accepts the following configuration from the associated dataset options:

Name Type Default Description
barPercentage number 0.9 Percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. more...
categoryPercentage number 0.8 Percent (0-1) of the available width each category should be within the sample width. more...
barThickness number|string Manually set width of each bar in pixels. If set to 'flex', it computes "optimal" sample widths that globally arrange bars side by side. If not set (default), bars are equally sized based on the smallest interval. more...
base number Base value for the bar in data units along the value axis. If not set, defaults to the value axis base value.
maxBarThickness number Set this to ensure that bars are not sized thicker than this.
minBarLength number Set this to ensure that bars have a minimum length in pixels.

Example dataset configuration

data: {
    datasets: [{
        barPercentage: 0.5,
        barThickness: 6,
        maxBarThickness: 8,
        minBarLength: 2,
        data: [10, 20, 30, 40, 50, 60, 70]
    }]
};

barThickness

If this value is a number, it is applied to the width of each bar, in pixels. When this is enforced, barPercentage and categoryPercentage are ignored.

If set to 'flex', the base sample widths are calculated automatically based on the previous and following samples so that they take the full available widths without overlap. Then, bars are sized using barPercentage and categoryPercentage. There is no gap when the percentage options are 1. This mode generates bars with different widths when data are not evenly spaced.

If not set (default), the base sample widths are calculated using the smallest interval that prevents bar overlapping, and bars are sized using barPercentage and categoryPercentage. This mode always generates bars equally sized.

Config Options

These are the customisation options specific to Bar charts. These options are looked up on access, and form together with the global chart configuration, Chart.defaults, the options of the chart.

Name Type Default Description
skipNull boolean undefined If true, null or undefined values will not be drawn

Scale Configuration

The bar chart sets unique default values for the following configuration from the associated scale options:

Name Type Default Description
offset boolean true If true, extra space is added to both edges and the axis is scaled to fit into the chart area.
gridLines.offsetGridLines boolean true If true, the bars for a particular data point fall between the grid lines. The grid line will move to the left by one half of the tick interval. If false, the grid line will go right down the middle of the bars. more...

Example scale configuration

options = {
    scales: {
        x: {
            gridLines: {
                offsetGridLines: true
            }
        }
    }
};

offsetGridLines

If true, the bars for a particular data point fall between the grid lines. The grid line will move to the left by one half of the tick interval, which is the space between the grid lines. If false, the grid line will go right down the middle of the bars. This is set to true for a category scale in a bar chart while false for other scales or chart types by default.

Default Options

It is common to want to apply a configuration setting to all created bar charts. The global bar chart settings are stored in Chart.overrides.bar. Changing the global options only affects charts created after the change. Existing charts are not changed.

barPercentage vs categoryPercentage

The following shows the relationship between the bar percentage option and the category percentage option.

// categoryPercentage: 1.0
// barPercentage: 1.0
Bar:        | 1.0 | 1.0 |
Category:   |    1.0    |
Sample:     |===========|

// categoryPercentage: 1.0
// barPercentage: 0.5
Bar:          |.5|  |.5|
Category:  |      1.0     |
Sample:    |==============|

// categoryPercentage: 0.5
// barPercentage: 1.0
Bar:             |1.0||1.0|
Category:        |   .5   |
Sample:     |==================|

Data Structure

All of the supported data structures can be used with bar charts.

Stacked Bar Chart

Bar charts can be configured into stacked bar charts by changing the settings on the X and Y axes to enable stacking. Stacked bar charts can be used to show how one data series is made up of a number of smaller pieces.

var stackedBar = new Chart(ctx, {
    type: 'bar',
    data: data,
    options: {
        scales: {
            x: {
                stacked: true
            },
            y: {
                stacked: true
            }
        }
    }
});

The following dataset properties are specific to stacked bar charts.

Name Type Description
stack string The ID of the group to which this dataset belongs to (when stacked, each group will be a separate stack).

Horizontal Bar Chart

A horizontal bar chart is a variation on a vertical bar chart. It is sometimes used to show trend data, and the comparison of multiple data sets side by side. To achieve this you will have to set the indexAxis property in the options object to 'y'. The default for this property is 'x' and thus will show vertical bars.

export const ExampleChart1 = () => { useEffect(() => { const cfg = { type: 'bar', data: { labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'], datasets: [{ axis: 'y', label: 'My First Dataset', data: [65, 59, 80, 81, 56, 55, 40], fill: false, backgroundColor: [ 'rgba(255, 99, 132, 0.2)', 'rgba(255, 159, 64, 0.2)', 'rgba(255, 205, 86, 0.2)', 'rgba(75, 192, 192, 0.2)', 'rgba(54, 162, 235, 0.2)', 'rgba(153, 102, 255, 0.2)', 'rgba(201, 203, 207, 0.2)' ], borderColor: [ 'rgb(255, 99, 132)', 'rgb(255, 159, 64)', 'rgb(255, 205, 86)', 'rgb(75, 192, 192)', 'rgb(54, 162, 235)', 'rgb(153, 102, 255)', 'rgb(201, 203, 207)' ], borderWidth: 1 }] }, options: { indexAxis: 'y', scales: { x: { beginAtZero: true } } } }; const chart = new Chart(document.getElementById('chartjs-1').getContext('2d'), cfg); return () => chart.destroy(); }); return

; }

Example

var myBarChart = new Chart(ctx, {
    type: 'bar',
    data: data,
    options: {
      indexAxis: 'y'
    }
});

Horizontal Bar Chart config Options

The configuration options for the horizontal bar chart are the same as for the bar chart. However, any options specified on the x-axis in a bar chart, are applied to the y-axis in a horizontal bar chart.

Internal data format

{x, y, _custom} where _custom is an optional object defining stacked bar properties: {start, end, barStart, barEnd, min, max}. start and end are the input values. Those two are repeated in barStart (closer to origin), barEnd (further from origin), min and max.