chart-column.md

Column Chart

API information regarding each chart is not addressed in this document. Refer to the API Guide.

Creating the Chart

There are two different ways to create the Column chart. The Column chart can be created through the constructor function or the static function. The two methods both result in returning an instance of the chart. The HTML element in which the chart is drawn el, data data, and the options object options are taken as parameters. If the element in which the chart is drawn contains elements other than the chart itself, it may unintentionally affect the chart. Therefore, it is recommended that you use an empty HTML element.

import { ColumnChart } from '@toast-ui/chart';

const chart = new ColumnChart({el, data, options});

// or

import Chart from '@toast-ui/chart';

const chart = Chart.columnChart({el, data, options});

Basic Chart

Data Type

categories values are shown on the y-axis, and the series value must be completed with the name and the data. The name is used to identify each series and its id must be unique.

const data = {
  categories: ['Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  series: [
    {
      name: 'Budget',
      data: [5000, 3000, 5000, 7000, 6000, 4000, 1000]
    },
    {
      name: 'Income',
      data: [8000, 4000, 7000, 2000, 6000, 3000, 5000]
    },
    {
      name: 'Expenses',
      data: [4000, 4000, 6000, 3000, 4000, 5000, 7000]
    },
    {
      name: 'Debt',
      data: [3000, 4000, 3000, 1000, 2000, 4000, 3000]
    }
  ]
}

range Chart

Data Type

The difference between the basic chart and the range chart lies in the type of the series data. The data is entered as an array, and the numerical values for the start and the end of the range should be entered in order.

const data = {
  categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  series: [
    {
      name: 'Seoul',
      data: [
        [-8.3, 0.3],
        [-5.8, 3.1],
        [-0.6, 9.1],
        [5.8, 16.9],
        [11.5, 22.6],
        [16.6, 26.6],
        [21.2, 28.8],
        [21.8, 30.0],
        [15.8, 25.6],
        [8.3, 19.6],
        [1.4, 11.1],
        [-5.2, 3.2],
      ],
    },
    {
      name: 'Busan',
      data: [
        [0, 10],
        [3.5, 13.1],
        [5.6, 13.1],
        [10.8, 16.9],
        [11.5, 18.6],
        [13.6, 20.6],
        [15.2, 20.8],
        [21.8, 26.0],
        [17.8, 23.6],
        [11.3, 16.6],
        [4.4, 11.1],
        [3.2, 11.2],
      ],
    },
  ],
}

Stack Group Chart

The stack option allows multiple series to be displayed on a single stacked chart. Adding the stackGroup attribute allows multiple series to be stacked together according to the stackGroup.

const data = {
  categories: [
    '0 ~ 9',
    '10 ~ 19',
    '20 ~ 29',
    '30 ~ 39',
    '40 ~ 49',
    '50 ~ 59',
    '60 ~ 69',
    '70 ~ 79',
    '80 ~ 89',
    '90 ~ 99',
    '100 ~',
  ],
  series: [
    {
      name: 'Male - Seoul',
      data: [4007, 5067, 7221, 8358, 8500, 7730, 4962, 2670, 6700, 776, 131],
      stackGroup: 'Male',
    },
    {
      name: 'Female - Seoul',
      data: [3805, 4728, 7244, 8291, 8530, 8126, 5483, 3161, 1274, 2217, 377],
      stackGroup: 'Female',
    },
    {
      name: 'Male - Incheon',
      data: [1392, 1671, 2092, 2339, 2611, 2511, 1277, 6145, 1713, 1974, 194],
      stackGroup: 'Male',
    },
    {
      name: 'Female - Incheon',
      data: [1320, 1558, 1927, 2212, 2556, 2433, 1304, 8076, 3800, 6057, 523],
      stackGroup: 'Female',
    },
  ],
};

const options = {
  series: {
    stack: true
  }
};

visible

Each series can have visible option. The visible option determines whether the series is displayed when the chart is first drawn. The default is true. The basic chart, range, and stack group chart use the same way.

const data = {
  categories: ['Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  series: [
    {
      name: 'Budget',
      data: [5000, 3000, 5000, 7000, 6000, 4000, 1000],
      visible: false
    },
    {
      name: 'Income',
      data: [8000, 4000, 7000, 2000, 6000, 3000, 5000]
    },
    {
      name: 'Expenses',
      data: [4000, 4000, 6000, 3000, 4000, 5000, 7000]
    },
    {
      name: 'Debt',
      data: [3000, 4000, 3000, 1000, 2000, 4000, 3000]
    }
  ]
}

If you create a chart by applying the above option, you can see that the checkbox is unchecked.

colorByCategories

Each series can have colorByCategories option. The colorByCategories option determines whether to paint the column color of the chart differently based on the categories. The default value is false.

const data = {
  categories: ['Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  series: [
    {
      name: 'Budget',
      data: [5000, 3000, 5000, 7000, 6000, 4000, 1000],
      colorByCategories: true
    }
  ]
}

Options

options should be used as an object.

type options = {
  chart?: {
    // ...
  },
  xAxis?: {
    // ...
  },
  yAxis?: {
    // ...
  },
  legend?: {
    // ...
  },
  exportMenu?: {
    // ...
  },
  tooltip?: {
    // ...
  },
  plot?: {
    // ...
  },
  responsive?: {
    // ...
  },
  theme?: {
    // More explanations in the `theme` chapter.

  },
  series?: {
    stack?: boolean | {
      type: 'normal' | 'percent';
      connector?: boolean;
    };
    selectable?: boolean;
    eventDetectType?: 'point' | 'grouped';
    diverging?: boolean;
    dataLabels?: {
      visible?: boolean;
      anchor?: 'center' | 'start' | 'end' | 'auto';
      offsetX?: number;
      offsetY?: number;
      formatter?: (value) => string;
      stackTotal?: {
        visible?: boolean;
        formatter?: (value) => string;
      };
    };
  }
};

Common options that can be used with this chart are not addressed in this document. Refer to the respective options guide. (Links: chart Options, Axis, Legend, Export, Tooltip, Plot, responsive Options )

stack

The stack option allows multiple series to form a stacked chart. The stack chart includes 'normal' type and the 'percent' type. The stack.connector option can be used to display the connectors (the line segments that connect the series according to the categories).

normal Type

Setting series.stack to true is identical to setting stack.type to 'normal'.

const options = {
  series: {
    stack: true
  }
}

// or

const options = {
  series: {
    stack: {
      type: 'normal'
    }
  }
}

Setting the connector to true displays the connectors.

const options = {
  series: {
    stack: {
      type: 'normal',
      connector: true
    }
  }
}

percent Type

Setting stack.type to 'percent' calculates the percentage of the sum for each and uses it to build the stack chart.

const options = {
  series: {
    stack: {
      type: 'percent'
    }
  }
}

Setting the connector to true displays the connectors.

const options = {
  series: {
    stack: {
      type: 'percent',
      connector: true
    }
  }
}

selectable

Makes the series selectable.

• default: false

const options = {
  series: {
    selectable: true
  }
};

selectable option, accompanied by on API's selectSeries and unselectSeries, grants further control over the series.

eventDetectType

Defines ways to select or detect the series via the mouse.

Type	Details
point	A single series is detected when a mouse comes within the individual series' detectable area. Only a single series is selected with respect to the current position of the cursor.
grouped	All data that are equal with respect to the y-axis are detected.

• default: point

Setting the eventDetectType to 'grouped' will detect all series that are equal with respect to the x-axis.

const options = {
  series: {
    eventDetectType: 'grouped'
  }
};

diverging

The diverging option, when used, allows users to create a diverging bar chart that diverges from the center like the population distribution chart. The diverging chart uses the first element as well as the second element from the data.series.

• default: false

const data = {
    categories: [
    '100 ~',
    '90 ~ 99',
    '80 ~ 89',
    '70 ~ 79',
    '60 ~ 69',
    '50 ~ 59',
    '40 ~ 49',
    '30 ~ 39',
    '20 ~ 29',
    '10 ~ 19',
    '0 ~ 9',
  ],
  series: [
    {
      name: 'Male',
      data: [383, 3869, 39590, 136673, 248265, 419886, 451052, 391113, 352632, 296612, 236243],
    },
    {
      name: 'Female',
      data: [1255, 12846, 83976, 180790, 263033, 412847, 435981, 374321, 317092, 272438, 223251],
    },
  ],
};

const options = {
  series: {
    diverging: true
  }
};

dataLabels

Data labels display information regarding the series on the chart. The following are the options for dataLabels.

type options = {
  ...
  series?: {
    dataLabels?: {
      visible?: boolean;
      offsetX?: number;
      offsetY?: number;
      formatter?: (value) => string;
      anchor: 'start' | 'center' | 'end' | 'auto';
      stackTotal?: {
        visible?: boolean;
        formatter?: (value) => string;
      };
    };
  };
};

Name	Type	Details
visible	boolean	Whether to make the data label visible
offsetX	number	X offset of the data label position
offsetY	number	Y offset of the data label position
formatter	function	Takes the value of the data as its parameter and defines the format to be displayed
anchor	'start' | 'center' | 'end' | 'auto'	Position of the data label (default: 'auto')
stackTotal	object	Defines the options related to displaying the total sum of the stack bar chart
stackTotal.visible	boolean	Whether to display the total sum label. If the chart is a stack chart, the default value is true.
stackTotal.formatter	function	Takes the value of data sum as its parameter and defines the format to be displayed

// basic
const options = {
  series: {
    dataLabels: { visible: true }
  }
};

// Stack column chart
const options = {
  series: {
    stack: true,
    dataLabels: { visible: true }
  }
};

Series Theme

The following is a list of themes that can be modified in the Column chart. The value for the data label style includes the basic labels, and when used with stack bar chart, it can be used to style the sum label that is displayed. Themes can be used to create a text bubble with a tail.

interface BoxChartSeriesTheme {
  barWidth?: number | string;
  areaOpacity?: number;
  colors?: string[];
  hover?: {
    color?: string;
    borderColor?: string;
    borderWidth?: number;
    shadowColor?: string;
    shadowOffsetX?: number;
    shadowOffsetY?: number;
    shadowBlur?: number;
    groupedRect?: {
      color?: string;
      opacity?: number;
    };
  };
  select?: {
    color?: string;
    borderColor?: string;
    borderWidth?: number;
    areaOpacity?: number;
    shadowColor?: string;
    shadowOffsetX?: number;
    shadowOffsetY?: number;
    shadowBlur?: number;
    groupedRect?: {
      color?: string;
      opacity?: number;
    };
    restSeries?: {
      areaOpacity?: number;
    };
  };
  connector?: {
    color?: string;
    lineWidth?: number;
    dashSegments?: number[];
  };
  dataLabels?: CommonDataLabelBubbleTheme & {
     stackTotal?: CommonDataLabelBubbleTheme;
  };
}

type CommonDataLabelBubbleTheme = {
  useSeriesColor?: boolean;
  lineWidth?: number;
  textStrokeColor?: string;
  shadowColor?: string;
  shadowBlur?: number;
  fontSize?: number;
  fontFamily?: string;
  fontWeight?: string | number;
  color?: string;
  textBubble?: {
    visible?: boolean;
    paddingX?: number;
    paddingY?: number;
    backgroundColor?: string;
    borderRadius?: number;
    borderColor?: string;
    borderWidth?: number;
    shadowColor?: string;
    shadowOffsetX?: number;
    shadowOffsetY?: number;
    shadowBlur?: number;
    arrow?: {
      visible?: boolean;
      width?: number;
      height?: number;
      direction?: 'top' | 'right' | 'bottom' | 'left';
    };
  };
};

Name	Type	Details
barWidth	number | string	Width of the series box
areaOpacity	number	Opacity of the entire area when all series are selected
colors	string[]	Colors for the series
hover	object	Style used when the cursor hovers over the series
hover.groupRect	object	Style used for the box area that covers the chart with respect to the x-axis when series.eventDetectType: 'grouped'
select	object	Style used when the series is selected and series.selectable: true
select.areaOpacity	number	Opacity of the selected series
select.groupRect	object	Style used for the box area that is selected with respect to the x-axis when series.eventDetectType: 'grouped'
select.restSeries	object	Style for series that have not been selected
dataLabels	object	Style for the data labels
dataLabels.useSeriesColor	boolean	Whether to use the series colors for the data label texts
dataLabels.lineWidth	number	Text stroke width
dataLabels.textStrokeColor	string	Text stroke color
dataLabels.shadowColor	string	Text shadow color
dataLabels.shadowBlur	number	Text shadow blue
dataLabels.fontSize	number	Font size
dataLabels.fontFamily	string	Font name
dataLabels.fontWeight	string	Font weight
dataLabels.color	string	Text color; does not work when useSeriesColor: true
dataLabels.textBubble	object	Text bubble configurations
dataLabels.textBubble.visible	boolean	Whether to use the text bubble
dataLabels.textBubble.paddingX	number	Horizontal padding
dataLabels.textBubble.paddingY	number	Vertical padding
dataLabels.textBubble.backgroundColor	string	Text bubble background color
dataLabels.textBubble.borderRadius	number	Text bubble border radius
dataLabels.textBubble.borderColor	string	Text bubble border color
dataLabels.textBubble.borderWidth	number	Text bubble border width
dataLabels.textBubble.shadowColor	string	Text bubble shadow color
dataLabels.textBubble.shadowOffsetX	number	Text bubble shadow x offset
dataLabels.textBubble.shadowOffsetY	number	Text bubble shadow y offset
dataLabels.textBubble.shadowBlur	number	Text bubble shadow blur
dataLabels.textBubble.arrow	object	Text bubble arrow configurations
dataLabels.textBubble.arrow.visible	boolean	Whether to use the text bubble arrows
dataLabels.textBubble.arrow.width	number	Arrow base width
dataLabels.textBubble.arrow.height	number	Arrow height
dataLabels.textBubble.arrow.direction	'top' | 'right' | 'bottom' | 'left'	Arrow direction
dataLabels.stackTotal	object	Label styles for stack charts; all style options available to dataLabels are also available with this option

The theme is configured using the theme option, and the series theme is configured using the theme.series. The following example changes the color, width, and the on-hover style for a column series.

const options = {
  theme: {
    series: {
      barWidth: 5,
      colors: ['#EDAE49', '#D1495B', '#00798C', '#30638E'],
      hover: {
        color: '#00ff00',
        borderColor: '#73C8E7',
        borderWidth: 3,
        shadowColor: 'rgba(0, 0, 0, 0.7)',
        shadowOffsetX: 4,
        shadowOffsetY: 4,
        shadowBlur: 6,
      },
    }
  }
};

The code above results as shown below.

The code below applies a theme to the data label to use text bubbles and to change the text styles.

const options = {
  series: {
    stack: true,
    dataLabels: { visible: true }
  },
  theme: {
    series: {
      dataLabels: {
        fontFamily: 'monaco',
        lineWidth: 2,
        textStrokeColor: '#ffffff',
        shadowColor: '#ffffff',
        shadowBlur: 4,
        stackTotal: {
          fontFamily: 'monaco',
          fontWeight: 14,
          color: '#ffffff',
          textBubble: {
            visible: true,
            paddingY: 6,
            borderWidth: 3,
            borderColor: '#00bcd4',
            borderRadius: 7,
            backgroundColor: '#041367',
            shadowOffsetX: 0,
            shadowOffsetY: 0,
            shadowBlur: 0,
            shadowColor: 'rgba(0, 0, 0, 0)'
          }
        }
      }
    }
  }
};