Bar Charts

SpreadJS supports several types of bar charts that compare categorical data using horizontal bars. Categories are displayed along the vertical axis, and aggregated values are shown on the horizontal axis.

Bar charts are particularly useful when category labels are long or when horizontal layout improves readability.

Notes:
All samples in this topic use the Sales table introduced in the Create Data Charts topic. Ensure that the data source has been configured before adding a chart.
For details about category and value encodings, see Bind Data Source.

Bar Chart

A bar chart uses rectangular bars to compare different categories or to illustrate the relationship between a category and a value. The length of each bar corresponds to the value it represents, making it easy to visually compare the magnitudes of different categories.

Bar charts are commonly used to display categorical data, such as comparing sales figures for different products or showing the distribution of the population across various age groups. They are versatile and effective in presenting data clearly and easy-to-understand manner.

An image of a bar chart is shown below:

SpreadJS DataChart compares aggregated Sales values by Product using horizontal bars configured with category, value, and color encodings.

Refer to the following sample code to add a bar chart.

// Bar Chart
const sheet = spread.getActiveSheet();
sheet.name("Bar Chart");
const dataChart = sheet.dataCharts.add('data-chart', 10, 10, 500, 300);
dataChart.setChartConfig({
    tableName: 'Sales',
    config: {
        header: {
            title: "Bar Chart"
        }
    },
    plots: [
        {
            type: GC.Spread.Sheets.DataCharts.DataChartType.bar,
            encodings: {
                values: [
                    {
                        field: "Sales",
                        aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
                    }
                ],
                category: {
                    field: "Product"
                },
                color: {
                    field: "Product"
                }
            },
        }
    ]
});

Bar Chart with Hierarchical Category

Bar charts support hierarchical category structures. Multiple grouping levels can be defined in the category encoding.

The following example shows a Bar chart grouped by Year → Quarter → Month.

SpreadJS hierarchical bar DataChart organizes aggregated sales through nested Year, Quarter, and Month category levels for detailed comparison.

// Bar Chart with Hierarchical Category
const sheet = spread.getActiveSheet();
sheet.name("Hierarchical Bar Chart");

const dataChart = sheet.dataCharts.add(
  'data-chart-hierarchy',
  10, 10, 500, 300
);

dataChart.setChartConfig({
  tableName: 'HierarchySales',
  config: {
    header: {
      title: "Hierarchical Bar Chart"
    }
  },
  plots: [{
    type: GC.Spread.Sheets.DataCharts.DataChartType.bar,
    encodings: {
      values: [{
        field: "sales",
        aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
      }],
      category: {
        field: "year",
        child: {
          field: "quarter",
          child: {
            field: "month"
          }
        }
      }
    }
  }]
});

Range Bar Chart

A range bar chart displays a value range for each category instead of a single aggregated value. Each bar represents one lower-to-upper interval, which makes this chart useful for comparing spreads, thresholds, or measurement ranges across categories.

An image of a range bar chart is shown below:

SpreadJS Range Bar DataChart compares each Product through horizontal intervals defined by aggregated Return and Sales fields as lower and upper vectors.

Refer to the following sample code to add a range bar chart.

// Range Bar Chart
const sheet = spread.getActiveSheet();
sheet.name("Range Bar Chart");
const dataChart2 = sheet.dataCharts.add('data-chart-2', 10, 10, 500, 300);
dataChart2.setChartConfig({
          tableName: 'Sales',
          config: {
                    header: {
                        // title settings
                        title: 'Range Bar Chart'
                    }
          },
          plots: [
                    {
                        type: GC.Spread.Sheets.DataCharts.DataChartType.rangeBar,
                        encodings: {
                                values: [{
                                vectors: {
                                    lower: { field: "Return" },
                                    upper: { field: "Sales" }
                                },
                                aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
                                }],
                            category: { field: 'Product' },
                            color: { field: 'Product' },
                        }
                    }
          ]
});

Positive and Negative Colors

Bar and Range Bar charts support positive and negative colors to distinguish values based on their direction or range relationship. The first color in the plot palette is used as the positive color, and the second color is used as the negative color.

Set usePositiveNegativeColors to true in the plot configuration to enable positive and negative colors.

config: {
    palette: ['#4CAF50', '#F44336'],
    usePositiveNegativeColors: true
}

For Bar charts, values greater than or equal to the baseline use the positive color, and values below the baseline use the negative color. The baseline defaults to 0 and can be adjusted by the axis origin.

SpreadJS Bar DataChart uses separate palette colors to distinguish values above or equal to the baseline from values below it.

For Range Bar charts, the positive color is used when the upper value is greater than or equal to the lower value. The negative color is used when the upper value is less than the lower value.

SpreadJS Range Bar DataChart colors intervals according to whether each upper value is greater or less than its corresponding lower value.

When positive and negative colors are enabled, color encoding does not take effect.

Stacked Bar Chart

A stacked bar chart displays multiple data series stacked on top of one another within a single bar. Each bar represents a category, and each segment of the bar represents a different sub-category or data series. The total height of the bar shows the total value for that category, while the segments illustrate how that total is divided among the sub-categories.

Stacked bar charts are effective for comparing the total size of different categories while also illustrating the composition of each category as parts of a whole. This allows viewers to easily see both the total value for each category and the relative proportions of the sub-categories within that total.

An image of a stacked bar chart is shown below:

SpreadJS stacked bar DataChart compares total Sales by Region while colored Product segments reveal each category’s internal composition.

Refer to the following sample code to add a stacked bar chart.

// Stacked Bar Chart
const sheet = spread.getActiveSheet();
sheet.name("Stacked Bar Chart");
const dataChart3 = sheet.dataCharts.add('data-chart-3', 10, 10, 500, 300);
dataChart3.setChartConfig({
         tableName: 'Sales',
         config: {
                    header: {
                        // title settings
                        title: 'Stacked Bar Chart'
                    },
         },
         plots: [
                    {
                        type: GC.Spread.Sheets.DataCharts.DataChartType.stackedBar,
                        encodings: {
                            values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                            category: { field: 'Region' },
                            details:[{field:'Product'}],
                            color: { field: 'Product' },
                        }
                    }
         ]
});

Percent Stacked Bar Chart

A percent stacked bar chart is similar to a stacked bar chart but with an add-on feature of displaying the data in percentage terms. Here, each bar represents the total value for a category, and the individual segments within the bar represent the proportion of each sub-category as a percentage of the total.

This type of chart is particularly useful when you want to compare the total sizes of different categories while also understanding the relative distribution or composition of each category in the percentage format. Percent stacked bar charts facilitate intuitive comparisons of the relative contributions of different sub-categories across categories, providing a clear visual representation of the percentage breakdown of data within each category.

An image of a percent stacked bar chart is shown below:

SpreadJS percent stacked bar DataChart normalizes each Region to 100 percent, enabling developers to compare proportional Product contributions across categories.

Refer to the following sample code to add a percent stacked bar chart.

// Percent Stacked Bar Chart
const sheet = spread.getActiveSheet();
sheet.name("Percent Stacked Bar Chart");
const dataChart4 = sheet.dataCharts.add('data-chart-4', 10, 10, 500, 300);
dataChart4.setChartConfig({
    tableName: 'Sales',
    config: {
        header: {
            // title settings
            title: 'Percent Stacked Bar Chart'
        }
    },
    plots: [
        {
            type: GC.Spread.Sheets.DataCharts.DataChartType.percentStackedBar,
            encodings: {
                values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                category: { field: 'Region' },
                details:[{field:'Product'}],
                color: { field: 'Product' },
            }
        }
    ]
});