Chart

Description #

<vaadin-chart> is a Web Component for creating high quality charts.

Basic use #

There are two ways of configuring your <vaadin-chart> 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.

<vaadin-chart title="The chart title" subtitle="The chart subtitle">
  <vaadin-chart-series
    type="column"
    title="The series title"
    values="[10, 20, 30]"
  ></vaadin-chart-series>
</vaadin-chart>

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 <vaadin-chart> in order to work properly.

Using JS API #

Use configuration property to set chart title, categories and data:

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 method to set chart title, categories and data:

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 documentation.

RTL support #

vaadin-charts as well as Highcharts 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

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

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.

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
• configuration.xAxis: An array of the chart's x axes. Detailed API for Axis object is available in API Site
• configuration.yAxis: An array of the chart's y axes. Detailed API for Axis object is available in API Site
• configuration.title: The chart title.

For detailed documentation of available API check the API site

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

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

Fired when the point is clicked.

point-drag #

Type: ChartPointDragEvent

Fired while dragging a point.

point-drag-start #

Type: ChartPointDragStartEvent

Fired when starting to drag a point.

point-drop #

Type: ChartPointDropEvent

Fired when the point is dropped.

point-legend-item-click #

Type: ChartPointLegendItemClickEvent

Fired when the legend item belonging to the point is clicked.

point-mouse-out #

Type: ChartPointMouseOutEvent

Fired when the mouse leaves the area close to the point.

point-mouse-over #

Type: ChartPointMouseOverEvent

Fired when the mouse enters the area close to the point.

point-remove #

Type: ChartPointRemoveEvent

Fired when the point is removed from the series.

point-select #

Type: ChartPointSelectEvent

Fired when the point is selected either programmatically or by clicking on the point.

point-unselect #

Type: ChartPointUnselectEvent

Fired when the point is unselected either programmatically or by clicking on the point

point-update #

Type: ChartPointUpdateEvent

Fired when the point is updated programmatically through .updateConfiguration() method.

series-after-animate #

Type: ChartSeriesAfterAnimateEvent

Fired when the series has finished its initial animation.

series-checkbox-click #

Type: ChartSeriesCheckboxClickEvent

Fired when the checkbox next to the series' name in the legend is clicked.

series-click #

Type: ChartSeriesClickEvent

Fired when the series is clicked.

series-hide #

Type: ChartSeriesHideEvent

Fired when the series is hidden after chart generation time.

series-legend-item-click #

Type: ChartSeriesLegendItemClickEvent

Fired when the legend item belonging to the series is clicked.

series-mouse-out #

Type: ChartSeriesMouseOutEvent

Fired when the mouses leave the graph.

series-mouse-over #

Type: ChartSeriesMouseOverEvent

Fired when the mouse enters the graph.

series-show #

Type: ChartSeriesShowEvent

Fired when the series is show after chart generation time.

xaxes-extremes-set #

Type: ChartXaxesExtremesSetEvent

Fired when when the minimum and maximum is set for the x axis.

yaxes-extremes-set #

Type: ChartYaxesExtremesSetEvent

Fired when when the minimum and maximum is set for the y axis.

Types #

ChartCategories #

export type ChartCategories = string[] | { [key: number]: string };

ChartCategoryPosition #

export type ChartCategoryPosition = 'bottom' | 'left' | 'right' | 'top';

ChartPointClickEvent #

/**
 * Fired when the point is clicked.
 */
export type ChartPointClickEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>;

ChartPointDragEvent #

/**
 * Fired while dragging a point.
 */
export type ChartPointDragEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>;

ChartPointDragStartEvent #

/**
 * Fired when starting to drag a point.
 */
export type ChartPointDragStartEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>;

ChartPointDropEvent #

/**
 * Fired when the point is dropped.
 */
export type ChartPointDropEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>;

ChartPointEvent #

export type ChartPointEvent = { target: Point; type: string };

ChartPointLegendItemClickEvent #

/**
 * Fired when the legend item belonging to the point is clicked.
 */
export type ChartPointLegendItemClickEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>;

ChartPointMouseOutEvent #

/**
 * Fired when the mouse leaves the area close to the point.
 */
export type ChartPointMouseOutEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>;

ChartPointMouseOverEvent #

/**
 * Fired when the mouse enters the area close to the point.
 */
export type ChartPointMouseOverEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>;

ChartPointRemoveEvent #

/**
 * Fired when the point is removed from the series.
 */
export type ChartPointRemoveEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>;

ChartPointSelectEvent #

/**
 * Fired when the point is selected either programmatically or by clicking on the point.
 */
export type ChartPointSelectEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>;

ChartPointUnselectEvent #

/**
 * Fired when the point is unselected either programmatically or by clicking on the point.
 */
export type ChartPointUnselectEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>;

ChartPointUpdateEvent #

/**
 * Fired when the point is updated programmatically through `.updateConfiguration()` method.
 */
export type ChartPointUpdateEvent = CustomEvent<{ point: Point; originalEvent: ChartPointEvent }>;

ChartSeriesAfterAnimateEvent #

/**
 * Fired when the series has finished its initial animation.
 */
export type ChartSeriesAfterAnimateEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>;

ChartSeriesCheckboxClickEvent #

/**
 * Fired when the checkbox next to the series' name in the legend is clicked.
 */
export type ChartSeriesCheckboxClickEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>;

ChartSeriesClickEvent #

/**
 * Fired when the series is clicked.
 */
export type ChartSeriesClickEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>;

ChartSeriesEvent #

export type ChartSeriesEvent = { target: Series; type: string };

ChartSeriesHideEvent #

/**
 * Fired when the series is hidden after chart generation time.
 */
export type ChartSeriesHideEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>;

ChartSeriesLegendItemClickEvent #

/**
 * Fired when the legend item belonging to the series is clicked.
 */
export type ChartSeriesLegendItemClickEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>;

ChartSeriesMouseOutEvent #

/**
 * Fired when the mouse leaves the graph.
 */
export type ChartSeriesMouseOutEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>;

ChartSeriesMouseOverEvent #

/**
 * Fired when the mouse enters the graph.
 */
export type ChartSeriesMouseOverEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>;

ChartSeriesShowEvent #

/**
 * Fired when the series is shown after chart generation time.
 */
export type ChartSeriesShowEvent = CustomEvent<{ series: Series; originalEvent: ChartSeriesEvent }>;

ChartStacking #

export type ChartStacking = 'normal' | 'percent' | null;

ChartXaxesExtremesSetEvent #

/**
 * Fired when when the minimum and maximum is set for the X axis.
 */
export type ChartXaxesExtremesSetEvent = CustomEvent<{
  axis: Axis;
  originalEvent: ExtremesObject & {
    target: Axis;
    type: string;
  };
}>;

ChartYaxesExtremesSetEvent #

/**
 * Fired when when the minimum and maximum is set for the Y axis.
 */
export type ChartYaxesExtremesSetEvent = CustomEvent<{
  axis: Axis;
  originalEvent: ExtremesObject & {
    target: Axis;
    type: string;
  };
}>;