Skip to content
amCharts 5

The <am5-chart> Element

<am5-chart> is an HTML element that builds a chart from a JSON config. There is no root element to create and no chart code to write: put the element on the page and give it a config.

Loading

Section titled “Loading”

With script tags, load index.js, plugins/json.js and element.js, in that order. Then load the files for the chart types the config uses, and any themes:

<script src="https://cdn.amcharts.com/lib/5/index.js"></script>
<script src="https://cdn.amcharts.com/lib/5/plugins/json.js"></script>
<script src="https://cdn.amcharts.com/lib/5/element.js"></script>
<script src="https://cdn.amcharts.com/lib/5/percent.js"></script>
<script src="https://cdn.amcharts.com/lib/5/themes/Animated.js"></script>

With npm, import defineChartElement() from the element module and call it once. The chart types a config uses are loaded automatically when the chart is built.

import { defineChartElement } from "@amcharts/amcharts5/element";


defineChartElement();

Adding a chart

Section titled “Adding a chart”

The config can be given right in the config attribute, as a JSON string:

<am5-chart config='{
  "type": "PieChart",
  "properties": {
    "series": [{
      "type": "PieSeries",
      "settings": { "valueField": "value", "categoryField": "category" },
      "properties": {
        "data": [
          { "category": "One", "value": 10 },
          { "category": "Two", "value": 9 },
          { "category": "Three", "value": 6 }
        ]
      }
    }]
  }
}'></am5-chart>

Or loaded from a file, with src:

<am5-chart src="chart.json"></am5-chart>

In code, the config property takes an object or a JSON string:

let element = document.createElement("am5-chart");


element.config = {
  type: "PieChart",
  properties: {
    series: [{
      type: "PieSeries",
      settings: { valueField: "value", categoryField: "category" },
      properties: {
        data: [
          { category: "One", value: 10 },
          { category: "Two", value: 9 },
          { category: "Three", value: 6 }
        ]
      }
    }]
  }
};


document.getElementById("chartdiv").appendChild(element);

Changing the config, by attribute or property, builds the chart again. Removing the element from the page disposes the chart. Moving the element keeps it.

Open in CodePen

Themes

Section titled “Themes”

Themes are not part of a config. With script tags, list theme names in the themes attribute, separated by spaces or commas. Each theme’s file must be loaded first.

<am5-chart src="chart.json" themes="Animated Dark"></am5-chart>

With npm, set theme classes on the themes property:

import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";


element.themes = [am5themes_Animated];

A theme with settings, such as Adaptive, goes in as a pair: the theme and its settings.

import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";
import am5themes_Adaptive from "@amcharts/amcharts5/themes/Adaptive";


element.themes = [
  am5themes_Animated,
  [am5themes_Adaptive, { baseColor: "#4150a0" }]
];

In the themes attribute, write such a list as JSON, with theme names:

<am5-chart src="chart.json" themes='["Animated", ["Adaptive", { "baseColor": "#4150a0" }]]'></am5-chart>

Maps and locales

Section titled “Maps and locales”

A map’s config names its geodata, e.g. "geoJSON": "am5geodata_worldLow", and a config’s root section can name a locale, e.g. "locale": "am5locales_de_DE", instead of carrying them. With script tags, load their files, and the element finds them as globals:

<script src="https://cdn.amcharts.com/lib/5/map.js"></script>
<script src="https://cdn.amcharts.com/lib/5/geodata/worldLow.js"></script>
<script src="https://cdn.amcharts.com/lib/5/locales/de_DE.js"></script>

With npm they are not globals. Import them and pass them in the resources property, under the names the config uses:

import am5geodata_worldLow from "@amcharts/amcharts5-geodata/worldLow";
import am5locales_de_DE from "@amcharts/amcharts5/locales/de_DE";


element.resources = { am5geodata_worldLow, am5locales_de_DE };

Size

Section titled “Size”

The chart fills the element. Size it with CSS like any other block element. If nothing gives it a height, it is 400 pixels high.

<am5-chart src="chart.json" style="height: 600px"></am5-chart>

SVG renderer

Section titled “SVG renderer”

Charts are drawn on canvas. To draw the chart as SVG instead, set renderer="svg":

<am5-chart src="chart.json" renderer="svg"></am5-chart>

Accessing the chart

Section titled “Accessing the chart”

Once the chart is built, the element’s root and chart properties hold its root element and the chart. From there, it can be changed with regular code, e.g. to add plugins.

The chart is built asynchronously. whenReady() returns a promise that resolves once it is built, or right away if it already is:

let element = document.querySelector("am5-chart");


element.whenReady().then(function(ev) {
  am5plugins_exporting.Exporting.new(ev.root, {
    menu: am5plugins_exporting.ExportingMenu.new(ev.root, {})
  });
});

The element also fires DOM events: ready when the chart is built (with root and chart in event.detail), and error if it could not be built (with the error in event.detail):

element.addEventListener("ready", function(ev) {
  console.log("Chart is ready", ev.detail.chart);
});


element.addEventListener("error", function(ev) {
  console.log("Chart could not be built", ev.detail);
});

In frameworks

Section titled “In frameworks”

Our packages for React, Vue, Angular and Svelte wrap the element: they load its code in the browser only, so pages can be rendered on a server, and take the config, themes, resources and renderer as props or inputs. See Integrations.

Custom element name

Section titled “Custom element name”

To use the element under another name, register it with defineChartElement(). The name must contain a hyphen.

import { defineChartElement } from "@amcharts/amcharts5/element";


defineChartElement("my-chart");

<am5-chart> stays registered too.