Basics

The purpose of this article is to get you acquainted with amCharts 4. In order not to overwhelm, we won't get into details of particular chart settings and configuration options - that's a point for other more specialized articles.

TypeScript / ES6 vs. JavaScript

To thwart all doubts, even if amCharts 4 is written in TypeScript, it does not force you to use it. If you don't use or don't even want to know what TypeScript is, that's fine with us.

If, on the other hand, you are already using TypeScript (you are if you are building applications with Angular2+) or some other ES6 app, you'll enjoy additional benefits amCharts 4 brings to the table, like code insight, strong type-check, etc.

Summing up, yes - you can use amCharts 4 in vanilla JavaScript applications, regular web pages just as well as in any ES6 and TS application.

NOTE TypeScript/ES6 code and JavaScript snippets might slightly differ. Make sure you select appropriate tab in code snippet for relevant code.

Requirements

The main and foremost requirement for amCharts 4 is JavaScript and SVG support.

While those two are nothing new - all modern browsers have (and have had for years) full support for both technologies for years - it still imposes certain limits on support of legacy platforms.

For example, SVG was introduced in Internet Explorer line of browsers in version 9. This means that V4 will not work on IE8 and below.

This restriction is tighter than any previous version of amCharts libraries, which supported VML as a fallback. We believe it's time to move on, and start forgetting decades-old, deprecated technologies. Hopefully, you agree ;).

Note about V3

Before you ask, V4 is not backwards compatible with code written for V3 or other amCharts products.

To make something truly ground-breaking, we had to make this sacrifice. Dragging 8-years-worth of legacy config did not go well.

So, even though your current package of amCharts experience is not going to be of great help here, you're still in for the treat, as V4 opens up data viz capabilities way beyond what was on the table before.

Installation

amCharts 4 is available through a number of channels. Below we'll outline a few.

NPM

You can use our official npm package @amcharts/amcharts4 to grab V4 and install into your application. It will even grab all the required dependencies.

npm install @amcharts/amcharts4

Yarn

For those of you using Yarn, you can use its add command to install our official npm package:

yarn add @amcharts/amcharts4

CDN

All of the compiled files for V4 is also available via amCharts CDN. Just point your <script> tags to https://www.amcharts.com/lib/4/..... E.g.:

<script src="//www.amcharts.com/lib/4/core.js"></script>
<script src="//www.amcharts.com/lib/4/charts.js"></script>

Download

You can download standalone ZIP archives containing everything you need to independently run amCharts 4 on our Downloads page.

GitHub

You can grab amCharts 4 directly from our GitHub repository.

GitHub offers standalone downloads, or you can clone the whole repo. Your call.

Map files / Geo-data

If you are going to be building geographical maps, you will also probably need the actual map files. Those are in an external package @amcharts/amcharts4-geodata. So make sure you install it as well.

NPM

npm install @amcharts/amcharts4-geodata

Yarn

yarn add @amcharts/amcharts4-geodata

Working with TypeScript / ES6

If you are using the charts in a TypeScript / ES6 application, read on. Otherwise jump to the next section which deals about using amCharts 4 in pure JavaScript.

Modules

All of the amCharts 4 functionality is grouped and compartmentalized into separate chunks, based on the function.

There's one central module (let's call it core.ts) that houses all the core functionality, like rendering, interaction, common controls, etc.

All chart-related functionality is grouped into another module: charts.ts, and all functionality related to maps into yet another module: maps.ts.

You'll always need the core one (core). And you'll need at least one of the modules with actual functionality, depending whether you are build a chart or a map. In case you are building both, you'll need to import both.

In your TS application, simply do the import of the modules you need to be using.

As mentioned above, you'll always need at least the core module, which, in amcharts4 package is called core.ts, plus the actual functionality module, like, say, charts.ts.

Your typical application would have something like this:

import * as am4core from "@amcharts/amcharts4/core";
import * as am4charts from "@amcharts/amcharts4/charts";

We like to import core module as am4core, and all our examples as well as code snippets on this website use this object naming, so we suggest you do the same.

Creating a chart

Now that we have required modules imported, let's try creating an actual chart.

A chart instance in V4 is instantiated using helper function create(), which is available in the am4core object.

It takes two parameters:

  • An id of a document container (such as <div> element) or a reference to it. The chart will be created within that container.
  • A class reference of the chart type we are creating. For a Pie chart it will be charts.PieChart, because that's how we have imported Pie chart functionality.
let chart = am4core.create("chartdiv", am4charts.PieChart);

Please note that an element with the id "chartdiv" must already exist in your document. The function will not create it.

Now that we have a chart instance, we'll need to configure it to actually display something.

For a Pie chart, we'll at least need to create a Series (am4charts.PieSeries) and add some data.

Here's how a code to our fully functioning Pie chart can look like:

// Import stuff
import * as am4core from "@amcharts/amcharts4/core";
import * as am4charts from "@amcharts/amcharts4/charts";

// Create chart instance
let chart = am4core.create("chartdiv", am4charts.PieChart);

// Create pie series
let series = chart.series.push(new am4charts.PieSeries());
series.dataFields.value = "litres";
series.dataFields.category = "country";

// Add data
chart.data = [{
	"country": "Lithuania",
	"litres": 501.9
}, {
	"country": "Czech Republic",
	"litres": 301.9
}, {
	"country": "Ireland",
	"litres": 201.1
}, {
	"country": "Germany",
	"litres": 165.8
}, {
	"country": "Australia",
	"litres": 139.9
}, {
	"country": "Austria",
	"litres": 128.3
}, {
	"country": "UK",
	"litres": 99
}, {
	"country": "Belgium",
	"litres": 60
}, {
	"country": "The Netherlands",
	"litres": 50
}];

// And, for a good measure, let's add a legend
chart.legend = new am4charts.Legend();

There's your first V4 chart, crated in TypeScript / ES6.

Working with JavaScript

Including required files

To save resources, all amCharts 4 functionality is divvied up in separate files, which you can include as <script> tags on-demand.

IMPORTANT There's one main file - core.js - which houses all the core functionality. It must always be included before any other amCharts JS files.

And there are separate files for charting functionality (charts.js) and for mapping (maps.js).

You can include those directly from amCharts CDN:

<script src="//www.amcharts.com/lib/4/core.js"></script>
<script src="//www.amcharts.com/lib/4/charts.js"></script>

Or download, install and load from your own server, e.g.:

<script src="//www.mywebsite.com/libs/amcharts/core.js"></script>
<script src="//www.mywebsite.com/libs/amcharts/charts.js"></script>

Now that we have required files ready we can start creating an actual chart.

amCharts 4 provides two ways of creating a chart and setting it's config in JavaScript: object-based approach and JSON.

Discussing cons and pros of both ways is beyond the scope of this article. (there's a separate one for that) We're just going to get you to know both of them.

About scopes

In JavaScript, all of the amCharts 4's core classes and functions are accessible via am4core global object.

Core classes and functions, are accessible directly, like am4core.create(), am4core.color(), new am4core.ColorSet(), etc.

Chart-related classes reside in am4charts global object. Mapping-related functionality in am4maps. Those are accessible via their relative global objects, e.g. am4charts.PieChart or am4maps.MapChart.

Some classes are universal and thus are accessible via multiple chart-type sub-objects, like for instance am4charts.Legend, am4maps.Legend, etc.

Object-based approach

Using this approach you create a chart and configure it by creating a chart object first, then adding other objects like series and legend to it, as well as configuring all those objects calling their respective methods, and/or setting their properties.

The function to create a chart instance is am4core.create(container, chart_type).

It takes two parameters:

  • container - an id of a document container (such as <div> element) or a reference to it. The chart will be created within that container.
  • chart_type - a class reference or a name of the class name representing the chart we are creating. For a Pie chart we might want to use am4charts.PieChart, or simply "PieChart".
// Including via class reference
var chart = am4core.create("chartdiv", am4charts.PieChart);

// But this would work just as well:
var chart = am4core.create("chartdiv", "PieChart");

Please note that an element with the id "chartdiv" must already exist in your document. The function will not create it.

Here's a complete example:

<script src="//www.amcharts.com/lib/4/core.js"></script>
<script src="//www.amcharts.com/lib/4/charts.js"></script>

<div id="chartdiv" style="width: 900px; height 800px;"></div>

<script>
// Create chart instance
var chart = am4core.create("chartdiv", am4charts.PieChart);

// Create pie series
var series = chart.series.push(new am4charts.PieSeries());
series.dataFields.value = "litres";
series.dataFields.category = "country";

// Add data
chart.data = [{
	"country": "Lithuania",
	"litres": 501.9
}, {
	"country": "Czech Republic",
	"litres": 301.9
}, {
	"country": "Ireland",
	"litres": 201.1
}, {
	"country": "Germany",
	"litres": 165.8
}, {
	"country": "Australia",
	"litres": 139.9
}, {
	"country": "Austria",
	"litres": 128.3
}, {
	"country": "UK",
	"litres": 99
}, {
	"country": "Belgium",
	"litres": 60
}, {
	"country": "The Netherlands",
	"litres": 50
}];

// And, for a good measure, let's add a legend
chart.legend = new am4charts.Legend();
</script>

Using JSON

All of the above, can be expressed as a single JavaScript object. (or JSON)

There's a dedicted tutorial about JSON-based config, so we're not get into details here, just present a version of the above object-based config, as on single JSON object:

<script src="//www.amcharts.com/lib/4/core.js"></script>
<script src="//www.amcharts.com/lib/4/charts.js"></script>

<div id="chartdiv" style="width: 900px; height 800px;"></div>

<script>
// Create chart instance in one go
var chart = am4core.createFromConfig({
	// Create pie series
	"series": [{
		"type": "PieSeries",
		"dataFields": {
			"value": "litres",
			"category": "country"
		}
	}],

	// Add data
	"data": [{
		"country": "Lithuania",
		"litres": 501.9
	}, {
		"country": "Czech Republic",
		"litres": 301.9
	}, {
		"country": "Ireland",
		"litres": 201.1
	}, {
		"country": "Germany",
		"litres": 165.8
	}, {
		"country": "Australia",
		"litres": 139.9
	}, {
		"country": "Austria",
		"litres": 128.3
	}, {
		"country": "UK",
		"litres": 99
	}, {
		"country": "Belgium",
		"litres": 60
	}, {
		"country": "The Netherlands",
		"litres": 50
	}],

	// And, for a good measure, let's add a legend
	"legend": {}

}, "chartdiv", am4charts.PieChart);
</script>

Notice, this time around we used different chart instantiation function: am4core.createFromConfig().

It works exactly like am4core.create() except it expects a JSON object holding chart config passed in before the other two parameters.

Wrapping up

By now, you should be able to know what it takes to create an amCharts 4 chart. Possibly, you already know what kind of technologies and approaches you'll be using.

As a next step, we suggest you explore the more detailed topics in Getting Started section. Use the main navigation to find a suitable topic or article.

Please note, that as V4 is new, so is the related documentation. Some of it is incomplete, some might be inaccurate, or outright empty. Please bear with us.

If you're going with TypeScript or ES6, this article is probably the next most logical step.

Decided on plain JavaScript? Go here.