> Markdown version of [Chart Configuration](https://vaadin.com/docs/v8/charts/webcomponents-api/charts-configuration). Section index: [llms.txt](https://vaadin.com/docs/v8/charts/llms.txt) # Chart Configuration All the chart content configuration of charts can be defined inside the `vaadin--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](#charts.configuration.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](#charts.configuration.plotoptions)) - `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](#charts.configuration.axes)) - `y-axis`: the Y axis or value axis (see [Axes](#charts.configuration.axes)) Please, see more details about these in the [API](https://demo.vaadin.com/vaadin-charts-api/). For data configuration, see ["Chart Data"](https://vaadin.com/docs/v8/charts/webcomponents-api/charts-data.md#charts.data). ## Plot Options The plot options are set under the `vaadin--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: ```html normal ``` See the [API](https://demo.vaadin.com/vaadin-charts-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. - `width` Defines the width of the chart either by pixels or as a percentual proportion of the drawing area. - `height` Defines the height of the chart either by pixels or as a percentual proportion of the drawing area. - `depth` Specifies the thickness of the chart in 3D mode. - `allow-point-select` 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*. - `border-color` Defines the border color of the chart elements. - `border-width` Defines the width of the border in pixels. - `center` 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%. - `sliced-offset` 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. - `visible` Specifies whether or not a chart is visible. Defaults to *true*. ## Axes 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](#figure.charts.configuration.axes.elements). [Image: charts axes lo] Chart Axis Elements Axis elements are added under the chart element. ```html ... Title ... ``` 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`. ```html ... ... ... ... ``` For a complete reference of the many configuration parameters for the axes, please refer to the [API](https://demo.vaadin.com/vaadin-charts-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. - LOGARITHMIC 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). - DATETIME 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. - CATEGORY 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(). ### Categories 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. ```html Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune ``` You can only set the category labels from the data point labels by setting the axis type to CATEGORY, as described earlier. ### Labels 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. ```html center -45 2 ``` Axis labels have the following configuration properties: - `align` 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. - `enabled` Whether labels are enabled or not. Defaults to 'true'. - `format` Formatting string for labels, as described in [Formatting Labels](#charts.configuration.format). Defaults to '{value}'. - `formatter` A JavaScript formatter for the labels, as described in [Formatting Labels](#charts.configuration.format). The value is available in the `this.value` property. The `this` object also has `axis`, `chart`, `isFirst`, and `isLast` properties. Defaults to: ```javascript 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. - `rotation` Defines rotation of labels in degrees. A positive value indicates rotation in clockwise direction. Labels are rotated at their alignment point. Defaults to 0. - `stagger-lines` 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`. - `step` Defines tick interval for showing labels, so that labels are shown at every *n*th tick. The default step is automatically determined, along with staggering, to avoid overlap. - `style` Defines style for labels. - `use-html` Allows using HTML in custom label formats. Otherwise, HTML is quoted. Defaults to false. - `x`,`y` 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](https://demo.vaadin.com/vaadin-charts-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. ```html -1 1 ``` ## Legend 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. - alignment Specifies the horizontal alignment of the legend box within the chart area. Possible values are `right`, `center`, and `left`. Defaults to `center`. - enabled Enables or disables the legend. Possible values are `true` and `false`. Defaults to `true`. - layout Specifies the layout direction of the legend items. Possible values are `vertical` and `horizontal`. Defaults to `horizontal`. - title Specifies the title of the legend. - vertical-align Specifies the vertical alignment of the legend box within the chart area. Possible values are `bottom`, `low`, `middle`, `high`, and `top`. Defaults to `bottom`. ```html City ``` The result can be seen in [Legend example](#figure.charts.configuration.legend). [Image: 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 - `series.name` 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: ``` ``` ### 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.