Migrating from V3

This article is meant to serve as an orientation for those who are currently working with amCharts version 3.

What is V3?

amCharts 3 series of products were released in 2013. It took most of its code base from an even earlier version - V2 - which was created in 2011 as a part of the whole "Flash is dead" ordeal.

That makes V3 code base over 7 years old, at the moment of advent of V4!

What is V4?

amCharts 4 is a completely new dataviz library. Re-imagined, re-designed, and re-written from the ground up.

We've designed the new version with the focus on three things:

  1. Flexibility;
  2. Performance;
  3. Extensibility.

The new version also follows the most modern practices for JavaScript library development, including module support, TypeScript use, etc.

Relation between V3 and V4

Not an upgrade

Important thing to understand is that V4 is not an upgrade to V3.

When we designed V4, we quickly understood that 7-year old API support was too big a handicap when trying to create something truly innovative, new, and super-flexible.

It was time to move on.

Use of V3 configs

Since V4 is not an upgrade, but rather a whole new library, it does will not work off configurations made for V3.

There's also no wrappers or converters, because the two products are conceptually too different.

For example, there's no way to map V3 graph's property to a V4 because there is no graph concept in V4.

Besides, V4 is way way way more advanced than V3. It would be a shame to restrict to the configuration options of the latter.

Compatibility

Good news is that even though V4 does not support V3 configs, it was specifically designed to not interfere.

This means you can display charts from both V3 and V4 at the same time on the same page.

This also means that you can do the migration gradually, one chart at a time.

Here's a quick demo to prove it:

See the Pen V3 and V4 on the same page by amCharts (@amcharts) on CodePen.24419

Terminology

Even though chart's logical components are still essentially the same in function, there is new terminology in place that might throw off a seasoned V3 user trying to move to V4.

Below is a table of such changes.

amCharts 3 amCharts 4
Graph Series (related tutorial)
Balloon Tooltip

Is V3 being deprecated?

No, not yet. We're still going to fix bugs, and provide technical support.

That said, we won't be introducing new features to it, though. That show now moved on to V4.

The timeline for V3 is looking like this:

Updates: End of 2019.

Support: End of 2020.

Migration

Should I migrate?

Short answer is - yes, you should. V4 is way more advanced as it is. And we're only just starting!

So, V4 is the way to go.

And, since there's no conflict between the two libraries, you can do it at your own pace, migrating one chart, then another, until you have none of V3 left.

That said, there are a few considerations you should take into account before taking a plunge.

Browser support

Important thing to consider before taking a plunge is your browser support requirement.

V3 had a fallback to VML for browsers that did not support SVG. VML is clunky, slow and buggy, but it was the only way to support old browsers.

V4 cuts that restricting umbilical cord. SVG support is now a requirement. SVG is 100% supported in all modern browsers, and has been for years. However, if your management requires you to support some dinosaur, like IE8, you should stick with V3. (or get new forward thinking management ;)

No Stock chart, yet

If you're using Stock Chart, you might want to hold off.

Stock chart is not yet available for V4. We're planning it for the first part of 2019. No exact ETA, yet. Sorry.

Comparing concepts

Here we will (very briefly) outline main conceptual differences between the two versions.

Serial VS XY

In V3 we had two separate chart types: Serial and XY. One was for linear information, the other for other two-dimensional scatter plots.

V4 has one universal XYChart. It supports any number of axes, of any types or combinations, so there's no point in distinguishing the two. You can have two value axes, two date axes, category axes, or multiple combinations of. You can even superimpose a scatter plot on a column chart, sky's the limit.

MORE INFO Check out "Axes" tutorial for more details.

Graphs VS Series

In V3, we had "graphs". This was a limited concept for the Serial and XY charts to indicate plots like line or column graphs.

In V4, we have "series". Series is a much more broader concept, used for any type of plot that has multiple element - not just line/columns, but also pie slice series, map object series, etc.

MORE INFO Check out "Series" tutorial for more details.

V3 Pie VS V4 Pie

In V3, Pie chart was proprietary bundle of settings.

In V4, Pie chart is a serial chart. And as all serial charts it can have multiple "pie series", allowing us to create nested donut charts.

Here's a demo of one.

SVG maps VS GeoJSON

In V3, we used proprietary JS and SVG format for map files. It was incredibly hard to create new maps.

In V4, we natively use GeoJSON - an open standard for geographical data. There are a lot of maps already available, ready to use in GeoJSON format, and even more in Esri shape file format, which is super easy to convert to GeoJSON that your granddad can do it.

V3 Radar VS V4 Radar

In V3, Radar chart was a pretty limited and proprietary. Only line graphs and only full circular, category-based charts could be used.

In V4, again, Radar is a full-fledged serial chart, with multi-type-axis / multi-type-series support, allowing incredible amount if various configurations, including radar scatters, stacked columns, wrap-around bands, etc.

Just check out the demo links below:

DEMOS Demo #1, demo #2, demo #3, demo #4, demo #5.

Animations

In V3, you could enable basic for graphs to "fly in". It also offered some assorted set visual property overrides, like for instance hover color.

In V4, everything can be animated. Data, colors, positions, sizes, opacity, zooms, like we said - anything.

V4 also introduced a concept of "states", where set of visual properties can be dynamically applied to elements, with smooth transitions. So, for example we don't have a property for hover color - we have a "hover state", which can override any and all properties of the element.

MORE INFO Check separate articles "Animations" and "States" for mode details.

Data

In V3, data could be dynamically updated by replacing the whole data set.

In V4, data can be added incrementally. Each series can also have own, independent data sets.

Check out this beautiful live chart!

The external data loader and parser is now built-in.

MORE INFO Check out our data-related articles: "Data" and "Loading External Data".

New chart types

In V3, we didn't have Treemaps and Sankey diagrams.

In V4, we do.

MORE INFO Check out dedicated "Treemap" and "Sankey diagram" articles for more details and demos.

Globals VS Modules

In V3, we had script files, that instantiated and relied on global variables.

In V4, we have modules, that are completely self-sufficient and do not rely on global variables.

Modules can be imported in ES6 and TypeScript applications.