Column Charts

SpreadJS supports several types of column charts that compare categorical data using vertical bars. In column charts, categories are plotted on the horizontal axis and aggregated values are displayed on the vertical axis.

Column charts are commonly used to compare values across categories or to visualize trends over time.

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.

Column Chart

A column chart is a common data visualization tool that compares different categories or displays trends over time. It consists of vertical bars where the height of each bar represents the value of the corresponding category, which allows a straightforward comparison between data points.

An image of a column chart is shown below:

SpreadJS DataChart uses vertical columns to compare the aggregated Sales value for each Product category from the Sales table.

The following example creates a basic column chart:

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

Column Chart with Hierarchical Category

Column charts support hierarchical category structures.

Multiple grouping levels can be defined in the category encoding.

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

SpreadJS hierarchical column DataChart groups aggregated sales columns through Year, Quarter, and Month category levels for detailed time-based comparison.

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

const dataChart = sheet.dataCharts.add(
  'data-chart-hierarchy',
  10, 10, 600, 400,
  GC.Spread.Sheets.DataCharts.DataChartType.column
);

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

Range Column Chart

A range column chart displays value ranges for each category using vertical bars.

Each column represents the interval between a lower and an upper value.

Range column charts are commonly used to visualize minimum and maximum values, confidence intervals, or value fluctuations.

An image of a stacked column chart is shown below:

SpreadJS range column DataChart displays the aggregated interval between Return as the lower vector and Sales as the upper vector for each Product category.

To define the lower and upper bounds, provide both fields within a single value configuration using the vectors structure (introduced in v19.1).

const sheet = spread.getActiveSheet();
sheet.name("Range Column Chart");

const dataChart = sheet.dataCharts.add(
  'data-chart-2',
  10, 10, 600, 400,
  GC.Spread.Sheets.DataCharts.DataChartType.column
);

dataChart.setChartConfig({
  tableName: 'Sales',
  config: {
    header: {
      title: "Range Column Chart"
    }
  },
  plots: [{
    type: GC.Spread.Sheets.DataCharts.DataChartType.rangeColumn,
    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

Column and Range Column 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 Column 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 column DataChart uses green columns for values at or above the baseline and red columns for values below the baseline.

For Range Column 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 column DataChart uses positive and negative colors to distinguish intervals where the upper value is respectively above or below the lower value.

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

Stacked Column Chart

A stacked column chart compares the total value of each category while also showing how sub-categories contribute to that total. Each column represents a category, and individual series are stacked vertically.

SpreadJS stacked column DataChart compares total Sales by Region while vertically stacked Product segments show each product’s contribution to the regional total.

The following example creates a stacked column chart:

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

Percent Stacked Column Chart

A percent stacked column chart is similar to a regular stacked column chart but displays data in percentage terms. In this chart, the height of each column represents the total value for that category, while the individual segments within the column show the proportion of each sub-category as a percentage of the total.

Percent stacked column charts are helpful when you want to compare the total sizes of different categories and also understand the relative distribution or composition of each category in terms of percentages. This type of chart provides a clearer picture of the overall distribution of data by allowing for easy comparisons of the relative contributions of different sub-categories across categories.

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

SpreadJS percent stacked column DataChart normalizes each Region column to show the proportional contribution of every Product to aggregated Sales.

The following example creates a percent stacked column chart:

// Percent Stacked Column Chart
const sheet = spread.getActiveSheet();
sheet.name("Percent Stacked Column Chart");
const dataChart4 = sheet.dataCharts.add('data-chart-3', 10, 10, 600, 400, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart4.setChartConfig({
    tableName: 'Sales',
    config: {
        header: {
            title: 'Percent Stacked Column Chart'
        }
    },
    plots: [
        {
            type: GC.Spread.Sheets.DataCharts.DataChartType.percentStackedColumn,

            encodings: {
                values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                category: { field: 'Region' },
                details:[{field:'Product'}],
                color: { field: 'Product' },
            }
        }
    ]
});