Upgrading Guide for Charts

Changes in Version 9

Vaadin Charts 9 comes with new chart types and brings back the API to style from Java. Since there are breaking changes introduced in Vaadin Charts 9, these changes cannot be backported to Vaadin 14 as part of the platform.

This guide will help you update your project to use the latest Charts version.

Summary

Below, you can see the main changes done for Charts 9 compared to previous versions:

Installing The Latest Charts Version

While the newer Charts was released for V17, a project running V14 in npm mode can use the new Charts by overriding the version at the project’s POM file:

<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-charts-flow</artifactId>
    <version>19.0.2</version>
</dependency>

Check the latest version on the Vaadin Flow Components release page.

Migration Guide

If you are planning to use Vaadin Charts 9 on a V14 platform, there are different approaches depending on the styling option picked.

Caution
Both CSS and Java styling cannot be used in the same project
While no error is thrown if different styling methods are used in the same project, only one method should be used across all charts, since having both could lead to unexpected results.

Java API for Styling

Vaadin Charts 9+ uses Java API for styling by default. This is more suitable for new projects or projects where the amount of charts is small or not heavily customised.

For example, that’s how the Example 1 from the CSS Styling guide would look like using the Java API:

Chart chart = new Chart();
Configuration configuration = chart.getConfiguration();

configuration.getChart().setType(ChartType.LINE);

configuration.getxAxis().setCategories("Jan", "Feb", "Mar", "Apr");

DataSeries ds = new DataSeries();
ds.setData(7.0, 6.9, 9.5, 14.5);

DataLabels callout = new DataLabels(true);
callout.setShape(Shape.CALLOUT);
callout.setY(-12);
// Setting the color to the data labels
callout.setColor(SolidColor.RED);
ds.get(1).setDataLabels(callout);
ds.get(2).setDataLabels(callout);
configuration.addSeries(ds);

// Adding a plot options to set the color to the markers
PlotOptionsLine plotOptions = new PlotOptionsLine();
plotOptions.getMarker().setFillColor(SolidColor.YELLOW);
chart.getConfiguration().setPlotOptions(plotOptions);

add(chart);

Using CSS Styling

If you want to upgrade Vaadin Charts, but want to keep using CSS styling, there are a few steps needed to make it work:

  1. Enable CSS style on every instance by calling setStyledMode(true):

    Chart chart = new Chart();
    Configuration conf = chart.getConfiguration();
    conf.getChart().setStyledMode(true);
  2. Import the charts default theme module to your view with:

    @JsModule("@vaadin/vaadin-charts/theme/vaadin-chart-default-theme")

For more detailed instructions, please check the "CSS Styling guide"

Changes in Version 6

Vaadin Charts 6 comes with some good enhancements, most notably: CSS styling. This necessitated removal of many Java style configuration API among other changes.

Summary

  • Upgraded to HighCharts 5

  • Styling is now primarily done with CSS

  • Dropped "size with units" sizing properties in favor of strings to take full advantage of browser capabilities

  • ZAxis is now a subclass of Axis

  • Getting PlotOptionsSeries no longer automatically creates a new instance

  • Gradient is no longer supported

  • Plot background image is no longer supported

  • SVG Generator is no longer supported

Replaced types

Old TypeReplaced By

PinchType

Dimension

ZoomType

Dimension

Dropped types

TypeUsed In

Handles

Navigator.handles

Dropped properties

TypeProperties

AbstractDataLabels (and subclasses)

backgroundColor, borderColor, borderRadius, borderWidth, color, reservedSpace, style

AreaOptions (and subclasses)

color, dashStyle, lineColor, lineWidth, negativeColor

Axis (and subclasses)

gridLineColor, gridLineWidth, minorGridLineColor, minorGridLineWidth, tickColor

AxisTitle

reserveSpace

AxisStyle

tickWidth, tickColor, gridLineColor, gridLineWidth

Background

backgroundColor, borderColor, borderWidth

ChartModel

backgroundColor, borderColor, plotBackgroundColor, plotBackgroundImage, plotBorderColor, selectionMarkerFill

ChartStyle

backgroundColor, plotBackgroundColor, plotBorderWidth, plotBorderColor, borderWidth, borderColor

ColumnOptions (and subclasses)

color

ContextButton

symbolFill, symbolSize, symbolStroke, symbolStrokeWidth

Credits

style

GaugeOptions (and subclasses)

zoneAxis, zones

Global

canvasToolsURL

Hover

lineWidth, lineWidthPlus, fillColor, lineColor

Labels

style

Legend

backgroundColor, borderColor, borderWidth, itemHiddenStyle, itemHoverStyle, itemStyle

LegendNavigation

activeColor, inactiveColor, style

LegendTitle

style

Loading

labelStyle, style

Marker

fillColor, lineColor, lineWidth

Navigation

menuItemHoverStyle, menuItemStyle, menuStyle

Navigator

handles, maskFill, outlineColor, outlineWidth

NoData

style

OhlcOptions (and subclasses)

color,lineWidth

PlotOptionsBoxplot

color, lineWidth, negativeColor

PlotOptionsBubble

color, dashStyle, lineWidth, negativeColor

PlotOptionsCandlestick

lineColor

PlotOptionsFlags

color, lineColor, lineWidth

PlotOptionsPolygon

color, dashStyle, lineWidth, negativeColor

PlotOptionsSeries

color, dashStyle, lineWidth, negativeColor

PlotOptionsTreemap

color

PlotOptionsWaterfall

dashStyle, lineColor

PointOptions (and subclasses)

color, dashStyle, lineWidth, negativeColor

PyramidOptions (and subclasses)

heightUnit, widthUnit

RangeSelector

buttonTheme, inputStyle, labelStyle

Select

fillColor, lineColor, lineWidth

StackLabels

style

Subtitle

style

Title

style

More information about Charts styling can be obtained in "CSS Styling".

Properties with new types

PropertyNew Type

ZAxis.title

AxisTitle

ZAxis.type

AxisType

ColumnOptions.zoneAxis

ZoneAxis

Label.textAlign

TextAlign

ChartModel.panKey

PanKey

Exporting.type

ExportingFileType

Background.shape

BackgroundShape