Root element

All charts and their controls are created in a root element. This tutorial examines some of its functionality and configuration options.

What is root element?

A root element is a kind of "wrapper" for everything else - charts, legend, labels, etc.- as well as repository for some chart-wide configuration options, such as locale, formatting options, themes, and others.

Whenever we create a new object in amCharts 5, we also pass in its root element, so that it correctly inherits themes and other settings.

Creating

We instantiate a root element by calling new method of Root class:

const root = am5.Root.new("chartdiv");
var root = am5.Root.new("chartdiv");

The parameter we pass into new() call is the id or reference of the DOM container we will want to place our chart in.

Using

As we already mentioned, root element will need to be passed into any other element we will create for the chart.

This is a requirement, so that the system knows which root element is being created for, as parent-child relation is not always apparent.

A reference to the root element is always the first parameter to the new() method call on any element being created, other than root itself.

For example, here's how root element is passed into an PieChart that is being newly created:

const chart = root.container.children.push(
  am5pie.PieChart.new(root, {})
);
var chart = root.container.children.push(
  am5pie.PieChart.new(root, {})
);

Configuring root

Formatters

Root element holds instances of the three formatters used throughout the charts and their elements:

PropertyClass
numberFormatterNumberFormatter
dateFormatterDateFormatter
durationFormatterDurationFormatter

Those are global formatters that define formats and related options used in formatting numbers, date/time, and duration.

MORE INFOFor more information, please refer to "Formatters: Global formatters".

Performance

amCharts 5 rendering engine will try to render charts and animations as smoothly as possible, cramming as many frames per second as possible.

The more frames per second animation plays, the smoother it looks.

However, if smoothness is not as important as resource usage, or chart-heavy page is suffering from performance-related issues, we can limit number of frames-per-second using root elements fps property:

root.fps = 30;
root.fps = 30;

The smaller the number, the less resources charts will use, at the expense of smoothness of animations.

Other configuration options

Root element contains some other global options, too:

Reusing

If we need to completely replace contents of the chart, we can dispose them, but keep root element for new chart.

To remove all elements from the root, simply clear children of its container:

root.container.children.clear();
root.container.children.clear();

Root element is now empty (as newly created) and can be used to add any other charts to it.

Reusing root element can be faster than completely destroying it and creating a new element.

Disposing

If we don't need root element anymore, we can dispose it, by calling its dispose() method:

root.dispose();
root.dispose();

Disposing root element will automatically dispose all its children charts as well. No need to dispose them separately.

NOTETrying to create a new root element in a container before disposing the old one that is currently residing there, will result in an error.

Controlling auto-resize

The root element will automatically resize itself if the size of its parent <div> element changes.

It can be disabled using autoResize property:

root.autoResize = false;
root.autoResize = false;

If set that way, root element will ignore any size changes in its parent and will remain at the same size it was first initialized with.

To manually trigger a resize for new dimensions, use resize() method:

root.resize();
root.resize();