--- title: Chart description: Chart element: vaadin-chart --- ## Description `` is a Web Component for creating high quality charts. ### Basic use There are two ways of configuring your `` element: **HTML API**, **JS API** and **JSON API**. Note that you can make use of all APIs in your element. #### Using HTML API `vaadin-chart` has a set of attributes to make it easier for you to customize your chart. ```html ``` > Note that while you can set type for each series individually, for some types, such as `'bar'`, `'gauge'` and `'solidgauge'`, you > have to set it as the default series type on `` in order to work properly. #### Using JS API Use [`configuration`](/elements/vaadin-chart#configuration) property to set chart title, categories and data: ```js const chart = document.querySelector('vaadin-chart'); // Wait for default configuration to be ready requestAnimationFrame(() => { const configuration = chart.configuration; configuration.setTitle({ text: 'The chart title' }); // By default there is one X axis, it is referenced by configuration.xAxis[0]. configuration.xAxis[0].setCategories(['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']); configuration.addSeries({ type: 'column', data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4] }); }); ``` #### Using JS JSON API Use [`updateConfiguration`](/elements/vaadin-chart#updateconfiguration) method to set chart title, categories and data: ```js const chart = document.querySelector('vaadin-chart'); chart.updateConfiguration({ title: { text: 'The chart title' }, subtitle: { text: 'Subtitle' }, xAxis: { categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] }, series: [{ type: 'column', data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4] }] }); ``` **Note:** chart style customization cannot be done via the JS or JSON API. Styling properties in the JSON configuration will be ignored. The following section discusses chart styling. ### CSS Styling Chart appearance is primarily controlled by CSS style rules. A comprehensive list of the supported style classes can be found at https://www.highcharts.com/docs/chart-design-and-style/style-by-css See also the [Chart Styling](https://vaadin.com/docs/latest/components/charts/css-styling) documentation. ### RTL support `vaadin-charts` as well as [Highcharts](https://www.highcharts.com/) by itself are not adjusting the layout based on the `dir` attribute. In order to make `vaadin-charts` display RTL content properly additional JSON configuration should be used. Each chart should be updated based on the specific needs, but general recommendations are: 1. Set `reversed` to true for xAxis (https://api.highcharts.com/highcharts/xAxis.reversed). 2. Set `useHTML` to true for text elements, i.e. `tooltip` (https://api.highcharts.com/highcharts/tooltip.useHTML). 3. Set `rtl` to true for `legend` (https://api.highcharts.com/highcharts/legend.rtl). ### Setting colors Although charts can be styled as described above, there is a simpler way for setting colors. Colors can be set using CSS custom properties `--vaadin-charts-color-{n}` (where `n` goes from `0 - 9`). For example `--vaadin-charts-color-0` sets the color of the first series on a chart. ## Properties ### additionalOptions **Type:** `Options | null | undefined` Represents additional JSON configuration. ### categories **Type:** `ChartCategories | null | undefined` If categories are present names are used instead of numbers for the category axis. The format of categories can be an `Array` with a list of categories, such as `['2010', '2011', '2012']` or a mapping `Object`, like `{0:'1',9:'Target (10)', 15: 'Max'}`. See also: [ChartCategories](#chartcategories) ### categoryMax **Type:** `number | null | undefined` Category-axis maximum value. Defaults to `undefined`. ### categoryMin **Type:** `number | null | undefined` Category-axis minimum value. Defaults to `undefined`. ### categoryPosition **Type:** `ChartCategoryPosition | null | undefined` The position of the category axis. Acceptable values are `left`, `right`, `top` and `bottom` except for bar charts which only accept `left` and `right`. With the default value, charts appear as though they have `category-position="bottom"` except for bar charts that appear as though they have `category-position="left"`. Defaults to `undefined` See also: [ChartCategoryPosition](#chartcategoryposition) ### chart3d **Type:** `boolean | null | undefined` Specifies whether to show chart in 3 or in 2 dimensions. Some display angles are added by default to the "chart.options3d" (`{alpha: 15, beta: 15, depth: 50}`). 3D display options can be modified via `additionalOptions`. The thickness of a Pie chart can be set on `additionalOptions` through `plotOptions.pie.depth`. 3D is supported by Bar, Column, Pie and Scatter3D charts. More info available at [Highcharts](https://www.highcharts.com/docs/chart-concepts/3d-charts). ### configuration **Type:** `Chart | undefined` Configuration object that exposes the JS Api to configure the chart. Most important methods are: - `addSeries (Object options, [Boolean redraw], [Mixed animation])` - `addAxis (Object options, [Boolean isX], [Boolean redraw], [Mixed animation])` - `setTitle (Object title, object subtitle, Boolean redraw)` Most important properties are: - `configuration.series`: An array of the chart's series. Detailed API for Series object is available in [API Site](http://api.highcharts.com/class-reference/Highcharts.Series) - `configuration.xAxis`: An array of the chart's x axes. Detailed API for Axis object is available in [API Site](http://api.highcharts.com/class-reference/Highcharts.Axis) - `configuration.yAxis`: An array of the chart's y axes. Detailed API for Axis object is available in [API Site](http://api.highcharts.com/class-reference/Highcharts.Axis) - `configuration.title`: The chart title. For detailed documentation of available API check the [API site](http://api.highcharts.com/class-reference/classes.list) ### emptyText **Type:** `string` Specifies the message displayed on a chart without displayable data. ### noLegend **Type:** `boolean | null | undefined` Specifies whether to hide legend or show. Legend configuration can be set up via additionalOptions property ### options **Type:** `Options` ### polar **Type:** `boolean | null | undefined` When present, cartesian charts like line, spline, area and column are transformed into the polar coordinate system. ### stacking **Type:** `ChartStacking | undefined` Specifies how series are stacked on top of each other. Possible values are null, "normal" or "percent". If "stack" property is not defined on the vaadin-chart-series elements, then series will be put into the default stack. See also: [ChartStacking](#chartstacking) ### subtitle **Type:** `string | undefined` Represents the subtitle of the chart. ### timeline **Type:** `boolean | null | undefined` Specifies whether the chart is a normal chart or a timeline chart. Value of this property is ignored for Gantt charts (type="gantt"). ### title **Type:** `string` Represents the title of the chart. ### tooltip **Type:** `boolean | null | undefined` Whether or not to show tooltip when hovering data points. ### type **Type:** `string | null | undefined` Sets the default series type of the chart. Note that `'bar'`, `'gauge'` and `'solidgauge'` should be set as default series type. ## Methods ### updateConfiguration **Type:** `(jsonConfiguration: Options, resetConfiguration?: boolean | undefined) => void` Update the chart configuration. This JSON API provides a simple single-argument alternative to the configuration property. Styling properties specified in this configuration will be ignored. To learn about chart styling please see the CSS Styling section above. ## Events ### chart-add-series **Type:** `CustomEvent` Fired when a new series is added. ### chart-after-export **Type:** `CustomEvent` Fired after a chart is exported. ### chart-after-print **Type:** `CustomEvent` Fired after a chart is printed. ### chart-before-export **Type:** `CustomEvent` Fired before a chart is exported. ### chart-before-print **Type:** `CustomEvent` Fired before a chart is printed. ### chart-click **Type:** `CustomEvent` Fired when clicking on the plot background. ### chart-drilldown **Type:** `CustomEvent` Fired when drilldown point is clicked. ### chart-drillup **Type:** `CustomEvent` Fired when drilling up from a drilldown series. ### chart-drillupall **Type:** `CustomEvent` Fired after all the series has been drilled up if chart has multiple drilldown series. ### chart-end-resize **Type:** `CustomEvent` Fired when the chart finishes resizing. ### chart-load **Type:** `CustomEvent` Fired when the chart is finished loading. ### chart-redraw **Type:** `CustomEvent` Fired when the chart is redraw. Can be called after a `Chart.configuration.redraw()` or after an axis, series or point is modified with the `redraw` option set to `true`. ### chart-selection **Type:** `CustomEvent` Fired when an area of the chart has been selected. ### point-click **Type:** [ChartPointClickEvent](#chartpointclickevent) Fired when the point is clicked. ### point-drag **Type:** [ChartPointDragEvent](#chartpointdragevent) Fired while dragging a point. ### point-drag-start **Type:** [ChartPointDragStartEvent](#chartpointdragstartevent) Fired when starting to drag a point. ### point-drop **Type:** [ChartPointDropEvent](#chartpointdropevent) Fired when the point is dropped. ### point-legend-item-click **Type:** [ChartPointLegendItemClickEvent](#chartpointlegenditemclickevent) Fired when the legend item belonging to the point is clicked. ### point-mouse-out **Type:** [ChartPointMouseOutEvent](#chartpointmouseoutevent) Fired when the mouse leaves the area close to the point. ### point-mouse-over **Type:** [ChartPointMouseOverEvent](#chartpointmouseoverevent) Fired when the mouse enters the area close to the point. ### point-remove **Type:** [ChartPointRemoveEvent](#chartpointremoveevent) Fired when the point is removed from the series. ### point-select **Type:** [ChartPointSelectEvent](#chartpointselectevent) Fired when the point is selected either programmatically or by clicking on the point. ### point-unselect **Type:** [ChartPointUnselectEvent](#chartpointunselectevent) Fired when the point is unselected either programmatically or by clicking on the point ### point-update **Type:** [ChartPointUpdateEvent](#chartpointupdateevent) Fired when the point is updated programmatically through `.updateConfiguration()` method. ### series-after-animate **Type:** [ChartSeriesAfterAnimateEvent](#chartseriesafteranimateevent) Fired when the series has finished its initial animation. ### series-checkbox-click **Type:** [ChartSeriesCheckboxClickEvent](#chartseriescheckboxclickevent) Fired when the checkbox next to the series' name in the legend is clicked. ### series-click **Type:** [ChartSeriesClickEvent](#chartseriesclickevent) Fired when the series is clicked. ### series-hide **Type:** [ChartSeriesHideEvent](#chartserieshideevent) Fired when the series is hidden after chart generation time. ### series-legend-item-click **Type:** [ChartSeriesLegendItemClickEvent](#chartserieslegenditemclickevent) Fired when the legend item belonging to the series is clicked. ### series-mouse-out **Type:** [ChartSeriesMouseOutEvent](#chartseriesmouseoutevent) Fired when the mouses leave the graph. ### series-mouse-over **Type:** [ChartSeriesMouseOverEvent](#chartseriesmouseoverevent) Fired when the mouse enters the graph. ### series-show **Type:** [ChartSeriesShowEvent](#chartseriesshowevent) Fired when the series is show after chart generation time. ### xaxes-extremes-set **Type:** [ChartXaxesExtremesSetEvent](#chartxaxesextremessetevent) Fired when the minimum and maximum is set for the x axis. ### yaxes-extremes-set **Type:** [ChartYaxesExtremesSetEvent](#chartyaxesextremessetevent) Fired when the minimum and maximum is set for the y axis. ## Types ### ChartCategories ```ts export type ChartCategories = string[] | { [key: number]: string }; ``` ### ChartCategoryPosition ```ts export type ChartCategoryPosition = 'bottom' | 'left' | 'right' | 'top'; ``` ### ChartPointClickEvent ```ts /** * Fired when the point is clicked. */ export type ChartPointClickEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>; ``` ### ChartPointDragEvent ```ts /** * Fired while dragging a point. */ export type ChartPointDragEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>; ``` ### ChartPointDragStartEvent ```ts /** * Fired when starting to drag a point. */ export type ChartPointDragStartEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>; ``` ### ChartPointDropEvent ```ts /** * Fired when the point is dropped. */ export type ChartPointDropEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>; ``` ### ChartPointEvent ```ts export type ChartPointEvent = { target: Point; type: string }; ``` ### ChartPointLegendItemClickEvent ```ts /** * Fired when the legend item belonging to the point is clicked. */ export type ChartPointLegendItemClickEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>; ``` ### ChartPointMouseOutEvent ```ts /** * Fired when the mouse leaves the area close to the point. */ export type ChartPointMouseOutEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>; ``` ### ChartPointMouseOverEvent ```ts /** * Fired when the mouse enters the area close to the point. */ export type ChartPointMouseOverEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>; ``` ### ChartPointRemoveEvent ```ts /** * Fired when the point is removed from the series. */ export type ChartPointRemoveEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>; ``` ### ChartPointSelectEvent ```ts /** * Fired when the point is selected either programmatically or by clicking on the point. */ export type ChartPointSelectEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>; ``` ### ChartPointUnselectEvent ```ts /** * Fired when the point is unselected either programmatically or by clicking on the point. */ export type ChartPointUnselectEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>; ``` ### ChartPointUpdateEvent ```ts /** * Fired when the point is updated programmatically through `.updateConfiguration()` method. */ export type ChartPointUpdateEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>; ``` ### ChartSeriesAfterAnimateEvent ```ts /** * Fired when the series has finished its initial animation. */ export type ChartSeriesAfterAnimateEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>; ``` ### ChartSeriesCheckboxClickEvent ```ts /** * Fired when the checkbox next to the series' name in the legend is clicked. */ export type ChartSeriesCheckboxClickEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>; ``` ### ChartSeriesClickEvent ```ts /** * Fired when the series is clicked. */ export type ChartSeriesClickEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>; ``` ### ChartSeriesEvent ```ts export type ChartSeriesEvent = { target: Series; type: string }; ``` ### ChartSeriesHideEvent ```ts /** * Fired when the series is hidden after chart generation time. */ export type ChartSeriesHideEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>; ``` ### ChartSeriesLegendItemClickEvent ```ts /** * Fired when the legend item belonging to the series is clicked. */ export type ChartSeriesLegendItemClickEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>; ``` ### ChartSeriesMouseOutEvent ```ts /** * Fired when the mouse leaves the graph. */ export type ChartSeriesMouseOutEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>; ``` ### ChartSeriesMouseOverEvent ```ts /** * Fired when the mouse enters the graph. */ export type ChartSeriesMouseOverEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>; ``` ### ChartSeriesShowEvent ```ts /** * Fired when the series is shown after chart generation time. */ export type ChartSeriesShowEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>; ``` ### ChartStacking ```ts export type ChartStacking = 'normal' | 'percent' | null; ``` ### ChartXaxesExtremesSetEvent ```ts /** * Fired when the minimum and maximum is set for the X axis. */ export type ChartXaxesExtremesSetEvent = CustomEvent<{ axis: Axis; originalEvent: ExtremesObject & { target: Axis; type: string; }; }>; ``` ### ChartYaxesExtremesSetEvent ```ts /** * Fired when the minimum and maximum is set for the Y axis. */ export type ChartYaxesExtremesSetEvent = CustomEvent<{ axis: Axis; originalEvent: ExtremesObject & { target: Axis; type: string; }; }>; ```