Documentation versions (currently viewingVaadin 8)

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Chart Configuration

All the chart content configuration of charts can be defined inside the vaadin-<type>-chart element.

The configuration properties in a chart element are summarized in the following:

  • data-series: the data for the chart

  • chart: general options

  • credits: credits label (text, position, href, enabled)

  • data: inteface for adding data from sources like CSV and HTML table

  • drilldown: options for drilldown

  • exporting: options for exporting module

  • labels: HTML labels

  • legend: a box containing a symbol and name fore each series item (see Legend)

  • loading: options to control the appearance of the loading screen

  • navigation: options for buttons and menus appearing in the exporting module

  • no-data: options for displaying a message like "No data to display"

  • pane: general options for combined X and Y axes set (only polar charts and angular gauges)

  • plot-options: wrapper object for config objects for each series type (see Plot Options)

  • subtitle: the charts subtitle

  • chart-title: the charts main title

  • tooltip: options for the tooltip

  • x-axis: the X axis or category axis (see Axes)

  • y-axis: the Y axis or value axis (see Axes)

Please, see more details about these in the API. For data configuration, see "Chart Data".

Plot Options

The plot options are set under the vaadin-<type>-chart element. The options are chart type specific, defined in type-spesific element inside the plot-options.

For example, the following enables stacking in column charts:


See the API documentation of plot-options and each chart type under it for more information about the chart-specific options.

Other Options

The following options are supported by some chart types.


Defines the width of the chart either by pixels or as a percentual proportion of the drawing area.


Defines the height of the chart either by pixels or as a percentual proportion of the drawing area.


Specifies the thickness of the chart in 3D mode.


Specifies whether data points, in whatever way they are visualized in the particular chart type, can be selected by clicking on them. Defaults to false.


Defines the border color of the chart elements.


Defines the width of the border in pixels.


Defines the center of the chart within the chart area by left and top coordinates, which can be specified either as pixels or as a percentage (as string) of the drawing area. The default is top 50% and left 50%.


In chart types that support slices, such as pie and pyramid charts, specifies the offset for how far a slice is detached from other items. The amount is given in pixels and defaults to 10 pixels.


Specifies whether or not a chart is visible. Defaults to true.


Different chart types may have one, two, or three axes; in addition to X and Y axes, some chart types may have a Z axis. These are represented by x-axis, y-axis, and z-axis, respectively. The X axis is usually horizontal, representing the iteration over the data series, and Y vertical, representing the values in the data series. Some chart types invert the axes and they can be explicitly inverted with getChart().setInverted() in the chart configuration. An axis has a caption and tick marks at intervals indicating either numeric values or symbolic categories. Some chart types, such as gauge, have only Y-axis, which is circular in the gauge, and some such as a pie chart have none.

The basic elements of X and Y axes are illustrated in Chart Axis Elements.

charts axes lo
Chart Axis Elements

Axis elements are added under the chart element.


A chart can have more than one Y-axis, usually when different series displayed in a graph have different units or scales. The association of a data series with an axis is done in the data-series using a property y-axis.

  <y-axis id="humidity">
  <data-series name="Humidity" y-axis = "humidity">

For a complete reference of the many configuration parameters for the axes, please refer to the API of Vaadin Charts.

Axis Type

Axes can be one of the following types, which you can set with type property.

LINEAR (default)

For numeric values in linear scale.


For numerical values, as in the linear axis, but the axis will be scaled in the logarithmic scale. The minimum for the axis must be a positive non-zero value ( log(0) is not defined, as it has limit at negative infinity when the parameter approaches zero).


Enables date/time mode in the axis. The date/time values are expected to be given in milliseconds since January 1st 1970 at 00:00:00 GMT. You can get the millisecond representation of a JavaScript Date object with the UTC() method.


Enables using categorical data for the axis, as described in more detail later. With this axis type, the category labels are determined from the labels of the data points in the data series, without need to set them explicitly with setCategories().


The axes display, in most chart types, tick marks and labels at some numeric interval by default. If the items in a data series have a symbolic meaning rather than numeric, you can associate categories with the data items. The category label is displayed between two axis tick marks and aligned with the data point. In certain charts, such as column chart, where the corresponding values in different data series are grouped under the same category. You can set the category labels with categories property. The list should match the items in the data series.

  <categories>Mercury, Venus, Earth, Mars,
              Jupiter, Saturn, Uranus, Neptune</categories>

You can only set the category labels from the data point labels by setting the axis type to CATEGORY, as described earlier.


The axes display, in most chart types, tick marks and labels at some numeric interval by default. You can modify the labels options with labels element inside the axis.

    <style color="green"></style>

Axis labels have the following configuration properties:


Defines the alignment of the labels relative to the centers of the ticks. On left alignment, the left edges of labels are aligned at the tickmarks, and correspondingly the right side on right alignment. The default is determined automatically based on the direction of the axis and rotation of the labels.

distance (only in polar charts)

Distance of labels from the perimeter of the plot area, in pixels.


Whether labels are enabled or not. Defaults to 'true'.


Formatting string for labels, as described in Formatting Labels. Defaults to '{value}'.


A JavaScript formatter for the labels, as described in Formatting Labels. The value is available in the this.value property. The this object also has axis, chart, isFirst, and isLast properties.

Defaults to:

function() {return this.value;}
max-stagger-lines (only horizontal axis)

When labels on the horizontal (usually X) axis are displayed so densely that they would overlap, they are automatically placed on alternating lines in "staggered" fashion. When number of lines is not set manually with staggerLines, this parameter defines the maximum number of such lines; value 1 disables automatic staggering. Default is 5 lines.


Defines rotation of labels in degrees. A positive value indicates rotation in clockwise direction. Labels are rotated at their alignment point. Defaults to 0.


Defines number of lines for placing the labels to avoid overlapping. By default 'undefined', and the number of lines is automatically determined up to max-stagger-lines.


Defines tick interval for showing labels, so that labels are shown at every nth tick. The default step is automatically determined, along with staggering, to avoid overlap.


Defines style for labels.


Allows using HTML in custom label formats. Otherwise, HTML is quoted. Defaults to false.


Offsets for the label’s position, relative to the tick position. X offset defaults to '0', but Y to 'null', which enables automatic positioning based on font size.

Gauge, pie, and polar charts allow additional properties.

For a complete reference of the many configuration parameters for the labels, please refer to the API of Vaadin Charts.

Axis Range

The axis range is normally set automatically to fit the data, but can also be set explicitly. The min and max elements in the axis configuration defines the minimum and maximum values of the axis range.



The legend is a box that describes the data series shown in the chart. It is enabled by default and is automatically populated with the names of the data series as defined in the series objects, and the corresponding color symbol of the series.


Specifies the horizontal alignment of the legend box within the chart area. Possible values are right, center, and left. Defaults to center.


Enables or disables the legend. Possible values are true and false. Defaults to true.


Specifies the layout direction of the legend items. Possible values are vertical and horizontal. Defaults to horizontal.


Specifies the title of the legend.


Specifies the vertical alignment of the legend box within the chart area. Possible values are bottom, low, middle, high, and top. Defaults to bottom.

<vaadin-line-chart id="basic-line">
  <legend layout="vertical" align="left" vertical-align="top">

The result can be seen in Legend example.

charts configuration legend
Legend example

Formatting Labels

Data point values, tooltips, and tick labels are formatted according to formatting configuration for the elements, with configuration properties described earlier for each element. Formatting can be set up for a data series or for individual data points. The format can be defined either by a 'format' string or by JavaScript function 'formatter', which are described in the following.

Using Format Strings

A formatting string contain free-form text mixed with variables. Variables are enclosed in brackets, such as "Here {point.y} is a value at {point.x}". In different contexts, you have at least the following variables available:

  • value in axis labels

  • point.x, point.y in data points and tooltips

  • in data points and tooltips

  • series.color in data points and tooltips

Values can be formatted according to a formatting string, separated from the variable name by a colon.

For numeric values, a subset of C printf formatting specifiers is supported. For example, "{point.y:%02.2f}" would display a floating-point value with two decimals and two leading zeroes, such as 02.30.

For dates, you can use a subset of PHP strftime() formatting specifiers. For example, "{value:%Y-%m-%d %H:%M:%S}" would format a date and time in the ISO 8601 format.

Using a JavaScript Formatter

A JavaScript formatter is given in a string that defines a JavaScript function that returns the formatted string. The value to be formatted is available in this.value for axis labels, or this.x, this.y for data points.

For example, to format tick labels on a chart axis, you could have:

  <labels formatter = "function () { return this.value / 1000 + 'Mm';}">

Simplified Formatting

Some contexts that display labels allow defining simple formatting for the labels. For example, data point tooltips allow defining prefix, suffix, and floating-point precision for the values.