← amCharts 5CONTENT HISTORY

Update to amCharts 5

Snapshot Nov 16, 2026 · 18:15 UTC · version 1.9.5

Collection source: downloaded plugin package.

WHAT CHANGED

First saved snapshot

No earlier snapshot is available to establish a change.

Save amCharts 5 and check future changes in Following.

Up to 3 plugins free · no card required.

Compare saved observations

Download comparison JSON
Full technical diff · 0 changed fields
Full snapshot data
{
  "description": "Build any chart with the amCharts 5 JavaScript library — XY (line, area, bar, column, candlestick, scatter), pie, donut, funnel, pyramid, geographic maps, hierarchy (treemap, sunburst, force-directed), flow (Sankey, chord, arc), radar, gauge, stock/financial, word cloud, Venn, Gantt, and timeline charts. Use this skill whenever the user mentions amCharts, asks for amCharts 5 code, needs a JavaScript chart built with amCharts, wants to create any data visualization using the amCharts library, is migrating from amCharts v4 to v5, or needs help with amCharts configuration, theming, exporting, tooltips, legends, or axis setup, including amCharts in React, Next.js, Vue, Nuxt, Angular, Svelte or React Native apps. Also use when the user mentions chart types that amCharts supports, even if they don't say \"amCharts\" explicitly, if amCharts is already present in the project or was discussed in the conversation.\n",
  "included_files": [
    {
      "relative_path": "references/flow.md",
      "size_in_bytes": 18548
    },
    {
      "relative_path": "references/gantt.md",
      "size_in_bytes": 15264
    },
    {
      "relative_path": "references/hierarchy.md",
      "size_in_bytes": 21027
    },
    {
      "relative_path": "references/json.md",
      "size_in_bytes": 29757
    },
    {
      "relative_path": "references/map.md",
      "size_in_bytes": 105390
    },
    {
      "relative_path": "references/pie.md",
      "size_in_bytes": 23683
    },
    {
      "relative_path": "references/radar.md",
      "size_in_bytes": 17591
    },
    {
      "relative_path": "references/stock.md",
      "size_in_bytes": 27087
    },
    {
      "relative_path": "references/timeline.md",
      "size_in_bytes": 15174
    },
    {
      "relative_path": "references/ui-elements.md",
      "size_in_bytes": 11494
    },
    {
      "relative_path": "references/venn.md",
      "size_in_bytes": 11288
    },
    {
      "relative_path": "references/wordcloud.md",
      "size_in_bytes": 16245
    },
    {
      "relative_path": "references/xy.md",
      "size_in_bytes": 57492
    }
  ],
  "name": "amcharts5",
  "skill_md_contents": "---\nname: amcharts5\ndescription: >\n  Build any chart with the amCharts 5 JavaScript library — XY (line, area, bar,\n  column, candlestick, scatter), pie, donut, funnel, pyramid, geographic maps,\n  hierarchy (treemap, sunburst, force-directed), flow (Sankey, chord, arc), radar,\n  gauge, stock/financial, word cloud, Venn, Gantt, and timeline charts. Use this\n  skill whenever the user mentions amCharts, asks for amCharts 5 code, needs a\n  JavaScript chart built with amCharts, wants to create any data visualization\n  using the amCharts library, is migrating from amCharts v4 to v5, or needs help\n  with amCharts configuration, theming, exporting, tooltips, legends, or axis\n  setup, including amCharts in React, Next.js, Vue, Nuxt, Angular, Svelte or\n  React Native apps. Also use when the user mentions chart types that amCharts supports, even\n  if they don't say \"amCharts\" explicitly, if amCharts is already present in the\n  project or was discussed in the conversation.\nmetadata:\n  author: amCharts\n  version: 1.0.0\n  category: code\n  tags: [charts, maps]\n  documentation: https://docs.amcharts.com/v5/\n  support: contact@amcharts.com\n---\n\n# amCharts 5\n\nBuild any chart with the amCharts 5 JavaScript charting library.\n\nDocs: https://docs.amcharts.com/v5/\n\n## Critical rules — apply to ALL chart types\n\n1. **Check demos first (if you can browse the web)** — Before building a chart, search or browse https://www.amcharts.com/demos/ for a demo that matches the user's request. Demo source code is the most reliable starting point — adapt it rather than writing from scratch. Skip this step if you have no web access.\n2. **Read the docs (if you can browse the web)** — For unfamiliar features or configuration, check https://docs.amcharts.com/v5/ for guides and tutorials. The docs explain concepts, patterns, and options that the class reference alone does not. Skip if you have no web access.\n3. **Always use amCharts 5** — never v3 or v4. The APIs are completely different.\n4. **Use `.new()` factory** — never `new ClassName()`. Every object is created via `ClassName.new(root, { settings })`.\n5. **Root is always the first argument** to `.new()` (except Root itself, which takes a div ID).\n6. **Set data last** — once data is set, objects are created. Configuration applied after may not take effect.\n7. **Colors use `am5.color()`** — e.g. `am5.color(0xff0000)`, `am5.color(\"#ff0000\")`, or `am5.color(\"rgb(255,0,0)\")`. Never raw hex strings.\n8. **Percent values use `am5.percent()`** — e.g. `am5.percent(50)`, not `50` or `\"50%\"`.\n9. **Every axis needs a renderer** — `am5xy.AxisRendererX.new(root, {})` or `AxisRendererY`.\n10. **CategoryAxis must receive data** — call `xAxis.data.setAll(data)` in addition to series data. Forgetting this is the #1 bug.\n11. **DateAxis values must be timestamps** — use `new Date().getTime()`, not Date objects.\n12. **Disposal is mandatory in SPAs** — in React, Vue, Angular, Svelte or React Native use amCharts' framework package, which creates and disposes the root for you (see \"Frameworks\"); without one, call `root.dispose()` on component unmount. Not `chart.dispose()`.\n13. **Style through amCharts, not CSS** — charts draw on canvas by default, so CSS cannot reach chart internals. Even with the optional SVG renderer (5.21.0) the shapes carry no per-element classes or ids, are rewritten as the chart redraws, and exports ignore page CSS. Use amCharts settings/templates/themes instead.\n14. **Dark backgrounds require Dark theme** — If the user requests or the page clearly has a dark background, always add `am5themes_Dark.new(root)` to `root.setThemes()` after Animated and ResponsiveMax. Without it, labels, grid, and tooltips will be invisible. If the background is not clearly dark, default to white/light and do NOT add the Dark theme unless asked.\n15. **Use default amCharts colors** — Do NOT invent custom color palettes unless the user explicitly asks for specific colors. amCharts assigns colors automatically from its built-in ColorSet. If you need a color programmatically, use `chart.get(\"colors\").getIndex(index)` or `chart.get(\"colors\").next()`. For pie/percent charts, use `series.get(\"colors\")` instead. With 3 or more series in one XY chart, the default colors are close blues and violets (hues 18° apart): set `chart.get(\"colors\").set(\"step\", 3)` before adding series, or use the `Colorblind` theme (see \"ColorSet\").\n16. **Every chart gets `Animated` and `ResponsiveMax` (5.22.0+)** — `root.setThemes([am5themes_Animated.new(root), am5themes_ResponsiveMax.new(root)])`, with a palette or `Dark` theme after them. ResponsiveMax fits labels and legends at any size and adapts the chart on small screens: axis labels are spaced to fit, legends shrink and then scroll, and scrollbars give way to pinch zoom on phones. Import `@amcharts/amcharts5/themes/ResponsiveMax`, or load `themes/ResponsiveMax.js` after `themes/Animated.js`. The theme is new in 5.22.0: for an older version, leave it out (in React Native, before react-native 5.0.3). One exception: a `Micro` sparkline keeps `Micro` alone.\n\n## Package / module map\n\n| Chart family | ES module import | CDN script | Main classes |\n|-------------|-----------------|-----------|-------------|\n| Core | `@amcharts/amcharts5` | `index.js` | Root, Theme, Legend, Tooltip, Label, Container |\n| XY charts | `@amcharts/amcharts5/xy` | `xy.js` | XYChart, axes, series |\n| Pie / Sliced | `@amcharts/amcharts5/percent` | `percent.js` | PieChart, SlicedChart, PieSeries, FunnelSeries, PyramidSeries, PictorialStackedSeries |\n| Map | `@amcharts/amcharts5/map` | `map.js` | MapChart, MapPolygonSeries, MapPointSeries, MapLineSeries, MapSankeySeries, PixelMapSeries, MapRasterSeries, NightSeries |\n| Hierarchy | `@amcharts/amcharts5/hierarchy` | `hierarchy.js` | Treemap, VoronoiTreemap, ForceDirected, Sunburst, Pack, Partition, Tree |\n| Flow | `@amcharts/amcharts5/flow` | `flow.js` | Sankey, Chord, ChordDirected, ChordNonRibbon, ArcDiagram |\n| Radar | `@amcharts/amcharts5/radar` | `radar.js` | RadarChart, AxisRendererCircular, AxisRendererRadial |\n| Stock | `@amcharts/amcharts5/stock` | `stock.js` | StockChart, StockPanel, StockToolbar |\n| Timeline | `@amcharts/amcharts5/timeline` | `timeline.js` | CurveChart, SerpentineChart, SpiralChart, CurveLineSeries, CurveColumnSeries |\n| Word cloud | `@amcharts/amcharts5/wc` | `wc.js` | WordCloud |\n| Venn | `@amcharts/amcharts5/venn` | `venn.js` | Venn |\n| Gantt | `@amcharts/amcharts5/gantt` | `gantt.js` | Gantt (also needs `xy.js` and `plugins/colorPicker.js`, both before `gantt.js`) |\n| Geodata | `@amcharts/amcharts5-geodata/*` | `geodata/*.js` | worldLow, usaLow, etc. |\n| Themes | `@amcharts/amcharts5/themes/Animated`, `@amcharts/amcharts5/themes/ResponsiveMax` (5.22.0) | `themes/Animated.js`, `themes/ResponsiveMax.js` | am5themes_Animated, am5themes_ResponsiveMax |\n| Exporting | `@amcharts/amcharts5/plugins/exporting` | `plugins/exporting.js` | Exporting, ExportingMenu |\n| JSON | `@amcharts/amcharts5/plugins/json` | `plugins/json.js` | ChartSerializer, JsonParser |\n| Chart element (5.21.0) | `@amcharts/amcharts5/element` | `element.js` (after `plugins/json.js`) | `<am5-chart>` — see \"Serializing to JSON\" |\n| Framework packages | `@amcharts/amcharts5-react`, `-vue`, `-angular`, `-svelte`, `-react-native` (separate npm packages) | — | `useAmChart`, `<AmChart>`, `[amChart]`, `attachAmChart` — see \"Frameworks\" |\n\n**Plain HTML, no bundler.** Load the script files (\"CDN script\" above) with `<script>` tags: `index.js` first, then the chart packages, then themes. They are on the amCharts CDN (`https://cdn.amcharts.com/lib/5/index.js`), and since 5.22.0 also in the npm package's `dist/` folder, so npm CDNs serve them:\n\n```html\n<script src=\"https://cdn.jsdelivr.net/npm/@amcharts/amcharts5@5.22.0/dist/index.js\"></script>\n<script src=\"https://cdn.jsdelivr.net/npm/@amcharts/amcharts5@5.22.0/dist/xy.js\"></script>\n<script src=\"https://cdn.jsdelivr.net/npm/@amcharts/amcharts5@5.22.0/dist/themes/Animated.js\"></script>\n<script src=\"https://cdn.jsdelivr.net/npm/@amcharts/amcharts5@5.22.0/dist/themes/ResponsiveMax.js\"></script>\n```\n\n- **Which CDN:** cdn.amcharts.com by default. Where only npm CDNs are allowed (Claude artifacts and other AI sandboxes, strict CSPs), use jsDelivr or unpkg (`https://unpkg.com/@amcharts/amcharts5@5.22.0/dist/index.js`). The files are also at `node_modules/@amcharts/amcharts5/dist/`.\n- **Pin one version for every file,** and use classic script tags, not `type=\"module\"`: the lazy parts (PDF, Excel and annotation export) load from the `deps/` folder beside `index.js`.\n- **Maps:** the package's `dist/geodata/` has only `worldLow.js` and `usaLow.js`. Other maps are in the `@amcharts/amcharts5-geodata` package's `dist/`, at the same path as below `geodata/` on the amCharts CDN (`dist/worldLow.js`, `dist/region/world/europeLow.js`), on unpkg (`https://unpkg.com/@amcharts/amcharts5-geodata@5.2.0/dist/worldLow.js`) but not jsDelivr, which refuses a package that large.\n- **PDF fonts** (`am5fonts_*`) are only on cdn.amcharts.com.\n\n**Bundling.** Keep code splitting on (esbuild: `splitting: true`, `format: \"esm\"`). With the stock toolbar's drawing or indicator controls, `<am5-chart>`, the JSON plugin or the exporting plugin, a single-file bundle inlines the exporting plugin's lazy parts (PDF, Excel, annotations), about 1 MB gzipped more: a stock chart with those controls loads about 275 KB gzipped split, 1.4 MB as one file (the toolbar itself and `PeriodSelector` add almost nothing). So does `import * as am5stock` when the whole namespace object is kept (assigned to a variable or `window`); `am5stock.StockChart` and the like keep only what they use. A stock chart without those controls bundles to about 130–200 KB, core + `xy` to about 170 KB. The script files gzipped (5.22.0): `index.js` + `xy.js` 182 KB, + `stock.js` 260 KB. Docs: https://docs.amcharts.com/v5/getting-started/#bundling.\n\n## Which reference to read\n\nBased on the chart type the user is building, read the relevant reference file for detailed API, patterns, and examples:\n\n| User wants | Read |\n|-----------|------|\n| Line, area, bar, column, candlestick, OHLC, scatter, stacked charts | `references/xy.md` |\n| Pie, donut, semi-circle, funnel, pyramid, pictorial stacked charts | `references/pie.md` |\n| World map, country map, choropleth, bubble map, point map, map sankey, pixel/dot map, satellite image or day/night map, globe with raised arcs | `references/map.md` |\n| Treemap, sunburst, force-directed, pack, partition, tree, org chart | `references/hierarchy.md` |\n| Sankey, chord, arc diagram, alluvial, flow visualization | `references/flow.md` |\n| Radar, spider, polar chart, gauge, speedometer, meter | `references/radar.md` |\n| Financial stock chart, candlestick with indicators, trading chart | `references/stock.md` |\n| Serpentine, spiral, curve chart, custom-shape timeline | `references/timeline.md` |\n| Gantt chart, project timeline, task management chart | `references/gantt.md` |\n| Word cloud, tag cloud, sentence cloud | `references/wordcloud.md` |\n| Venn diagram, set overlap visualization | `references/venn.md` |\n| Interactive controls: buttons, sliders, steppers, color pickers | `references/ui-elements.md` |\n| A chart as a JSON config: \"JSON config\", \"amCharts JSON\", a `<am5-chart>` element, a framework package's `config` prop, a Chart Maker link | `references/json.md` (with the chart type's reference for its settings) |\n\nIf the chart type is unclear, start with `references/xy.md` — XY charts are by far the most common.\n\nIf the user asks about core setup (theming, colors, exporting, legends, tooltips, disposal, responsive) without a specific chart type, the information below is sufficient — no reference file needed. For a chart in a React, Vue, Angular, Svelte or React Native app, read \"Frameworks\" below as well as the chart type's reference.\n\n## Root element setup\n\n```js\nconst root = am5.Root.new(\"chartdiv\"); // div id or HTMLElement reference\n\n// Apply theme(s): Animated and ResponsiveMax on every chart (ResponsiveMax from 5.22.0); a palette or Dark after them\nroot.setThemes([am5themes_Animated.new(root), am5themes_ResponsiveMax.new(root)]);\n\n// Set locale (optional)\nimport am5locales_de_DE from \"@amcharts/amcharts5/locales/de_DE\";\nroot.locale = am5locales_de_DE;\n\n// Set date/number formats (optional)\nroot.dateFormatter.setAll({ dateFormat: \"yyyy-MM-dd\" });\nroot.numberFormatter.setAll({ numberFormat: \"#,###.##\" });\n```\n\nOne Root per DOM element: a second `am5.Root.new()` on the same element throws \"You cannot have multiple Roots on the same DOM node\", so dispose the old root first. Separate elements on one page can each have their own Root (for example, a chart in a modal), and each is disposed on its own.\n\n**Canvas or SVG (5.21.0).** Charts draw on canvas by default. `am5.SVGRenderer` draws the same chart as live SVG instead — it can only be chosen when the root is created:\n\n```js\nconst root = am5.Root.new(\"chartdiv\", { renderer: am5.SVGRenderer });\n// or, before creating any root, for every chart on the page:\nam5.Root.defaultRenderer = am5.SVGRenderer;\n```\n\nCharts look and behave the same with either (text is measured the same way, interaction and image export work as usual); only blend modes `DST_OVER`, `SRC_ATOP` and `XOR` are canvas-only (drawn as normal in SVG, with a console warning). Keep the canvas default unless the user asks for SVG in the page. An SVG **file** does not need it — `am5.renderToSVG()` and the exporting menu make SVG from either renderer (see \"Exporting\"). In SVG mode pointer input is still resolved by amCharts (the `<svg>` layers have `pointer-events=\"none\"`), so attach handlers with `events.on()`, not DOM listeners.\n\n**Available themes** (as of 5.22.0):\n\n| Kind | Themes |\n|------|--------|\n| Behavioral | `Animated` (animations), `ResponsiveMax` (5.22.0, on every chart: fits labels, legends and scrollbars; see \"Responsive rules\"), `Micro` (stripped-down micro charts, alone), `Responsive` (the older size-based theme, which mostly hides parts on small charts) |\n| Light palettes | `Dataviz`, `Frozen`, `Kelly`, `Material`, `Moonrise`, `Spirited`, `Ember`, `Nord`, `Pastel`, `Petroleum`, `Savanna`, `Colorblind` (Okabe-Ito, color-blindness safe), `Patterns` (pattern fills instead of flat colors) |\n| Dark | `Dark`, `Midnight`, plus a dark variant of most palettes: `DatavizDark`, `FrozenDark`, `KellyDark`, `MaterialDark`, `MoonriseDark`, `SpiritedDark`, `NordDark`, `PastelDark`, `ColorblindDark`, `PatternsDark` |\n| Parameterized (5.20.0) | `Monochrome`, `Adaptive` — see below |\n\nPalette themes are additive: put them after `Animated` and `ResponsiveMax`, e.g. `root.setThemes([am5themes_Animated.new(root), am5themes_ResponsiveMax.new(root), am5themes_Nord.new(root)])`. The `*Dark` variants already carry dark interface colors, so do NOT also add `Dark`.\n\n## Colors\n\n```js\n// From hex integer or CSS string — only these forms are valid\nam5.color(0xff0000)\nam5.color(\"#ff0000\")\nam5.color(\"rgb(255, 0, 0)\")\n\n// WRONG — {r,g,b} objects are NOT accepted\n// am5.color({ r: 255, g: 0, b: 0 })  // throws!\n\n// Lighten / darken — STATIC methods on am5.Color (NOT instance methods)\nam5.Color.lighten(am5.color(0xff0000), 0.3)   // lighter\nam5.Color.lighten(am5.color(0xff0000), -0.3)  // darker (use negative value; there is NO .darken())\nam5.Color.brighten(am5.color(0xff0000), 0.3)  // brighter\n// WRONG: am5.color(0xff0000).lighten(0.3) — this does NOT work, lighten is not an instance method\n\n// Color sets (auto-cycle)\nchart.get(\"colors\").getIndex(0)   // first color in palette\nchart.get(\"colors\").next()        // next color\n\n// Custom color set\nchart.get(\"colors\").set(\"colors\", [\n  am5.color(0x095256),\n  am5.color(0x087f8c),\n  am5.color(0x5aaa95),\n  am5.color(0x86a873),\n  am5.color(0xbb9f06)\n]);\n\n// A color on a scale through several colors (5.21.2): position 0–1, clamped, colors evenly spaced\nvar ic = root.interfaceColors;\nvar mid = am5.Color.interpolateColors(0.5, [ic.get(\"negative\"), ic.get(\"warning\"), ic.get(\"positive\")]);   // = warning\n```\n\nThe interface color `warning` (5.21.2) is a yellow between `negative` (red) and `positive` (green), for the middle of a bad-to-good scale. Prefer `interpolateColors()` through it over `am5.Color.interpolate(t, negative, positive)`, whose middle is brown.\n\n## Legend\n\n```js\nconst legend = chart.children.push(am5.Legend.new(root, {\n  centerX: am5.percent(50),\n  x: am5.percent(50),\n  layout: root.horizontalLayout  // or verticalLayout, gridLayout\n}));\n// XY charts:\nlegend.data.setAll(chart.series.values);\n// Pie/Percent charts:\nlegend.data.setAll(series.dataItems);\n```\n\n**A legend that fits: `autoFit: true` (5.22.0).** As room runs out, it fits the legend in steps:\n1. Empty value labels give their room back.\n2. A legend that fits at three quarters of its size or more gets smaller.\n3. One that wouldn't fit even then scrolls instead, usually at full size, and item names too wide are shortened.\n4. When not even one row fits, the legend is hidden.\n\nAbove or below the chart it takes at most 30% of the chart's height, beside it at most 40% of its width. A `width`, `height`, `maxWidth`, `maxHeight`, `scale` or `verticalScrollbar` you set on the legend is kept. Without it, a long legend below a pie can take the whole chart and leave the pie no room.\n\n**A right-to-left chart (5.22.0)**, for Hebrew or Arabic: set the Root's `direction` when you create it.\n\n```js\nconst root = am5.Root.new(\"chartdiv\", { direction: \"rtl\" });\n```\n\n- Text with no `direction` of its own is drawn right to left.\n- Legends start on the right: a row's first item is on the right, and a vertical legend lines its items up on its right edge. Each item reads from the right: the marker, then the name, then the value.\n- `\"ltr\"` keeps everything left to right, e.g. an English chart on a `dir=\"rtl\"` page.\n- Not set, text follows the CSS direction of the chart's element, and legends stay left to right.\n\nSet it in `Root.new()` (or a JSON config's `root` section), not later. Drop `reverseChildren` from legend items in older code, or the legend flips back.\n\nA `Label` with a `width` keeps its text inside its box for every `textAlign` and `direction` since 5.22.0: `left` and `right` are the box's sides, `start` and `end` follow the direction.\n\n## Tooltip\n\n```js\nseries.set(\"tooltip\", am5.Tooltip.new(root, {\n  labelText: \"{name}: {valueY}\"   // data placeholders in {}\n}));\n```\n\n**Placeholders:** `{name}`, `{valueX}`, `{valueY}`, `{categoryX}`, `{categoryY}`, `{value}`, `{category}`, `{valuePercentTotal}`, `{sum}`.\n\n**Inline formatting:** `\"[bold]{name}[/]: [fontSize: 20px]{value}[/]\"`\n\nNumbers in placeholders get thousands separators (`{year}` shows `2,024`): see \"Number formats\".\n\n**A tooltip with no text renders as an empty bubble.** Enabling a `am5.Tooltip` without `labelText` (or `series.tooltipText`) shows a blank tooltip. Series text lives on `tooltip.labelText` or `series.set(\"tooltipText\", ...)`; for column/bar charts the text usually goes on `series.columns.template.set(\"tooltipText\", \"{categoryX}: {valueY}\")`.\n\n### Styling a tooltip\n\nThe tooltip background is a **`PointedRectangle`** (NOT a `RoundedRectangle`), so it has a single `cornerRadius` — there are no `cornerRadiusTL/TR/BL/BR`:\n\n```js\nconst tooltip = am5.Tooltip.new(root, { labelText: \"{valueY}\" });\n\n// Background color + shape — must turn OFF getFillFromSprite, else bg copies the series color\ntooltip.set(\"getFillFromSprite\", false);\ntooltip.get(\"background\").setAll({\n  fill: am5.color(0x000000),\n  fillOpacity: 0.8,\n  stroke: am5.color(0xffffff),\n  strokeOpacity: 0.3,\n  cornerRadius: 6        // single radius — PointedRectangle, not four corners\n});\n\n// Text color — must turn OFF autoTextColor (it auto-picks for contrast), then set on the label\ntooltip.set(\"autoTextColor\", false);\ntooltip.label.setAll({ fill: am5.color(0xffffff) });   // tooltip.label is read-only accessor\n\nseries.set(\"tooltip\", tooltip);\n```\n\n`getStrokeFromSprite` (default `false`) copies the sprite's stroke color when `true`.\n\n### Shared vs per-sprite tooltip\n\nSetting **only** `tooltipText` on a sprite (no `tooltip:` instance anywhere on it) is enough to get a hover tooltip: the sprite lazily resolves the **Root's shared default `Tooltip`** (`sprite.getTooltip()` returns it). You only need your own `am5.Tooltip.new(root, {...})` when that element's tooltip must **look different** from the shared one, or on XY charts, where series/axis tooltips are **cursor-driven** rather than hover-driven and need their own instance.\n\nSo for non-XY charts do not create a Tooltip per series — set `tooltipText` on the right template and style the look once on the shared tooltip:\n\n```js\n// Where tooltipText goes on non-XY charts\npieSeries.slices.template.set(\"tooltipText\", \"{category}: {value}\");   // pie / funnel / venn slices\nhierarchySeries.nodes.template.set(\"tooltipText\", \"{category}: {sum}\"); // hierarchy nodes\nflowSeries.nodes.nodes.template.set(\"tooltipText\", \"{name}\");           // flow nodes\nflowSeries.links.template.set(\"tooltipText\", \"{sourceId} → {targetId}: {value}\"); // flow links\nwordCloud.labels.template.set(\"tooltipText\", \"{category}: {value}\");    // word cloud words\npolygonSeries.mapPolygons.template.set(\"tooltipText\", \"{name}\");        // map polygons (map points: the bullet sprite)\n\n// Style the shared tooltip once — it lives on root.container (applies everywhere no dedicated Tooltip was set)\nvar shared = root.container.get(\"tooltip\");\nshared.set(\"getFillFromSprite\", false);\nshared.get(\"background\").setAll({ fill: am5.color(0x000000), fillOpacity: 0.8 });\n```\n\n**A tooltip on a `Container` has no background.** The tooltip takes its color from the target's `fill` (`getFillFromSprite`, default `true`), and a Container has none, even with a `background`: only black text shows. Put `tooltipText` on a child that has a fill. An invisible circle as the last child still takes hover and gives a bigger target. Or set `getFillFromSprite: false` and a background fill (above).\n\n```js\npointSeries.bullets.push(function (root, series, dataItem) {\n  var box = am5.Container.new(root, {});\n  box.children.push(am5.Circle.new(root, { radius: 8, fill: am5.color(0xcc3300) }));\n  box.children.push(am5.Label.new(root, { text: \"{name}\", populateText: true, x: 10, centerY: am5.p50, fontSize: 12 }));\n  box.children.push(am5.Circle.new(root, {\n    radius: 12, fill: am5.color(0xcc3300), fillOpacity: 0,   // invisible; its fill colors the tooltip\n    tooltipText: \"{name}\"\n  }));\n  return am5.Bullet.new(root, { sprite: box });\n});\n```\n\n## Number formats\n\nNumbers in `{placeholders}` use `root.numberFormatter`'s `numberFormat` (default `\"#,###.#####\"`: separators, at most 5 decimals). Format one placeholder with `{valueY.formatNumber('#,###.00')}`; a `ValueAxis` has its own `numberFormat` and `tooltipNumberFormat`. A `numberFormatter` on a tooltip or a template doesn't change placeholders. Docs: https://docs.amcharts.com/v5/concepts/formatters/formatting-numbers/#rounding-to-whole-numbers, https://docs.amcharts.com/v5/concepts/formatters/formatting-numbers/#years-without-thousands-separators.\n\n| Format | 6708.044000000005 | 1.125 | 2024 |\n|---|---|---|---|\n| `#,###` | 6,708.044000000005 | 1.125 | 2,024 |\n| `#,###.` | 6,708 | 1 | 2,024 |\n| `#,###.#` | 6,708 | 1.1 | 2,024 |\n| `#,###.00` | 6,708.04 | 1.13 | 2,024.00 |\n| `#` | 6708.044000000005 | 1.125 | 2024 |\n\n- The part after `.` decides rounding. With no `.` nothing is rounded, unlike Excel's `#,###`; a format ending in `.` rounds to a whole number. For animated values (`{valueXWorking}` in a bar race) use `'#,###.'`.\n- Every number placeholder gets a thousands separator, so a year `{year}` shows `2,024`. Use `{year.formatNumber('#')}`, or keep the year a string in the data.\n- Positive, negative and zero formats are split by `|`, not `;` (`\"#,###;'-'#,###;0\"` prints `500;-500;0`). The negative part still gets a minus unless it has the `s` modifier: `\"#,###|(#,###s)|'-'\"` gives `1,000`, `(1,000)`, `-`. Before 5.22.0, `#,###s` lost the thousands separator.\n- On a value axis with fractional steps, a trailing `.` makes duplicate labels (`1, 1, 2, 2`); use `maxPrecision: 0` there.\n\n## Chart title\n\nDo NOT add titles as HTML elements — they are outside the chart and won't appear in exports. Add an `am5.Label` to the container BEFORE the chart, and set `verticalLayout`:\n\n```js\n// Option 1: directly on root.container\nroot.container.children.push(am5.Label.new(root, {\n  text: \"Chart Title\",\n  fontSize: \"1.3em\",\n  x: am5.p50,\n  centerX: am5.p50\n}));\nroot.container.set(\"layout\", root.verticalLayout);\n\nvar chart = root.container.children.push(am5xy.XYChart.new(root, { ... }));\n\n// Option 2: with a wrapper container\nvar container = root.container.children.push(am5.Container.new(root, {\n  width: am5.p100,\n  height: am5.p100,\n  layout: root.verticalLayout\n}));\ncontainer.children.push(am5.Label.new(root, {\n  text: \"Chart Title\",\n  fontSize: \"1.3em\",\n  x: am5.p50,\n  centerX: am5.p50\n}));\nvar chart = container.children.push(am5xy.XYChart.new(root, { ... }));\n```\n\n## Exporting\n\n```js\nimport * as am5plugins_exporting from \"@amcharts/amcharts5/plugins/exporting\";\n\nconst exporting = am5plugins_exporting.Exporting.new(root, {\n  menu: am5plugins_exporting.ExportingMenu.new(root, {}),\n  filePrefix: \"my-chart\",\n  pngOptions: { quality: 0.8 },\n  pdfOptions: { addURL: true }\n});\n```\n\n**SVG export (5.21.0)** works whichever renderer draws the chart. The `ExportingMenu` lists \"SVG\" by default (`svgOptions: { disabled: true }` removes it; `svgOptions: { precision: 3 }` sets the decimals); in code use `exporting.download(\"svg\")`, `exporting.getSVG()` (markup) or `exporting.exportSVG()` (data URI). Without the plugin, the core has `am5.renderToSVG()`:\n\n```js\n// The chart as last drawn — after a change, wait for the frame to be drawn\nroot.events.once(\"frameended\", function () {\n  const svg = am5.renderToSVG(root);                              // SVG markup string\n  const part = am5.renderToSVG(series, { background: \"#ffffff\" }); // one element, where it sits on the chart\n});\n```\n\nOptions: `width`, `height`, `precision` (default `3`), `idPrefix` (`\"am5-\"`; vary it when several SVGs share a page), `title` (screen-reader name; default the Root `ariaLabel`), `background` (CSS color; default transparent), `includeNonExportable` (5.21.5, default `false`: also write elements marked `exportable: false`, such as scrollbar grips). Left out: elements with `exportable: false` (unless `includeNonExportable`), cross-origin images without CORS, and fully transparent elements. Since 5.21.5 the SVG suits design tools such as Figma: fonts are attributes with sizes in pixels, text is placed without `dominant-baseline`, patterns are drawn as shapes, and layers are named after series, data items, axes and the legend.\n\n## Responsive rules\n\n**`am5themes_ResponsiveMax` (5.22.0) goes on every chart** (Critical rule 16). It fits labels and legends at any size, and adapts the chart on small screens, hiding parts only as the last step:\n\n```js\nimport am5themes_ResponsiveMax from \"@amcharts/amcharts5/themes/ResponsiveMax\";   // script tag: themes/ResponsiveMax.js\nroot.setThemes([am5themes_Animated.new(root), am5themes_ResponsiveMax.new(root)]);\n```\n\nWhat it does:\n- It turns on the settings in the table below: `autoLabels` on axis renderers and on series (pie labels included), `autoFit` on legends, and `autoHide` on a chart's scrollbars.\n- A vertical scrollbar hides on a chart 400 px wide or less, a horizontal one on a chart 300 px tall or less. A stock chart is measured whole, not by panel.\n- When the chart's div is 400 px or less in either direction, text is drawn at 85% of its size (`fontSize: \"0.85em\"`).\n- Scrollbar margins shrink too: a horizontal scrollbar's when the div is 400 px tall or less, a vertical one's when it is 400 px wide or less.\n- Labels you add with your own `fontSize`, such as a title, shrink when the div is smaller than 600 × 450 px, down to three quarters of their size.\n- Axis labels get `keepInView`: x axis labels on a chart 400 px wide or less, y axis labels on one 400 px tall or less.\n- A Gantt chart 600 px wide or less drops its expand, collapse and color buttons. Its two scrollbars hide at 500 px wide or less, and the horizontal one also at 400 px tall or less; its plot is dragged to move.\n\nA setting you set in code wins over the theme: `autoLabels: false` on one series or renderer turns that part off. The theme also has `addRule()`, as below.\n\nThe settings also work on their own. All are off by default:\n\n| Setting | On | Does |\n|---|---|---|\n| `autoLabels: true` | any axis renderer (`AxisRendererX`, `AxisRendererY`, radar's) | Spaces labels by their own size. A short axis gets more labels (up to about eight). A category axis shows every label that fits, even closer than `minGridDistance`. Long labels are spaced by their width, so there can be fewer than without it. A label that would be cut off, or overlap another axis's labels, is hidden. |\n| `autoLabels: true` | `PieSeries` | Moves the pie aside or makes it smaller (down to half the chart's shorter side) to make room. Labels then wrap, are shortened or are hidden, smallest slices first. See `references/pie.md`, \"Labels\". |\n| `autoLabels: true` | any other series | Hides a bullet's label while it overlaps an earlier label or is cut off. The bullet's shape stays. |\n| `keepInView: true` | axis labels (`renderer.labels.template`) | A label whose category or date period is only partly in view, such as the first month after zooming, moves into the part in view instead of hiding. It hides only where that part is too short for it. For unrotated labels inside their cell (`location` or `multiLocation` between 0 and 1), as they are by default when every category or period has a label. Where the grid steps over several (every 2 months), labels sit on grid lines unless `multiLocation` is set, e.g. `0.5`. Not for value axis labels. On by default for a Gantt chart's date rows. |\n| `autoFit: true` | `Legend` | See \"Legend\". |\n| `autoHide: 300` | a chart's `scrollbarX` / `scrollbarY` | Hides the scrollbar when the chart is that many pixels across it or less: a `scrollbarX` by the chart's height, a `scrollbarY` by its width. Meanwhile it turns on `pinchZoomX` / `pinchZoomY`, unless that is set in code. |\n\n`ChartSerializer` saves these settings when you set them in code. It does not save what they decide (hidden labels, a smaller legend, the pinch zoom), nor what a theme turns on, so a config saved from a small chart opens full size.\n\n**Rules of your own** go on the `am5themes_ResponsiveMax` instance (before 5.22.0, on `am5themes_Responsive`, which also hides parts of its own):\n\n```js\nconst responsive = am5themes_ResponsiveMax.new(root);\nresponsive.addRule({\n  relevant: am5themes_ResponsiveMax.widthXS,  // <= 200px\n  applying: function() {\n    legend.setAll({ visible: false });\n  },\n  removing: function() {\n    legend.setAll({ visible: true });\n  }\n});\nroot.setThemes([am5themes_Animated.new(root), responsive]);\n```\n\n## Heat rules\n\nColor or size elements by value. Requires `calculateAggregates: true` on the series (unless `minValue`/`maxValue` are set manually).\n\n```js\n// Color columns by value\nseries.set(\"heatRules\", [{\n  target: series.columns.template,\n  dataField: \"valueY\",\n  min: am5.color(0xe5dc36),\n  max: am5.color(0x5faa46),\n  key: \"fill\"\n}]);\n\n// Scale bullet radius by value\nseries.set(\"heatRules\", [{\n  target: bulletTemplate,        // am5.Template.new({})\n  dataField: \"value\",\n  min: 3,\n  max: 30,\n  key: \"radius\"\n}]);\n\n// Through more than two values (5.21.2): `stops` in place of min/max, e.g. red–yellow–green\nvar ic = root.interfaceColors;\nseries.set(\"heatRules\", [{\n  target: series.columns.template,\n  dataField: \"valueY\",\n  stops: [ic.get(\"negative\"), ic.get(\"warning\"), ic.get(\"positive\")],\n  key: \"fill\"\n}]);\n```\n\nA `radius` rule is linear in radius: areas grow with the square of the value, and the smallest value gets `min`, not zero. For bubbles whose area matches the value, set the radius in the bullet function instead: `radius: maxRadius * Math.sqrt(value / maxValue)` (see `references/xy.md`, \"Scatter / Bubble chart\").\n\n**Heat rule settings:**\n\n| Setting | Type | Description |\n|---------|------|-------------|\n| `target` | Template | Element template to apply heat to |\n| `key` | string | Setting to modify: `\"fill\"`, `\"radius\"`, `\"opacity\"`, `\"strokeWidth\"`, `\"fontSize\"`, etc. |\n| `dataField` | string | Data field for the value: `\"valueY\"`, `\"value\"`, `\"valueX\"`, etc. |\n| `min` | color/number | Value applied at the lowest data value |\n| `max` | color/number | Value applied at the highest data value |\n| `neutral` | color/number | Value for elements whose data item has no value (otherwise they keep the template's) |\n| `stops` | array | Values for a scale through more than two (5.21.2), in place of `min`/`max`: the lowest data value gets the first, the highest the last, blended between. Numbers, percents or colors, all of one kind |\n| `minValue` | number | Override auto-calculated min (skips `calculateAggregates`; `0` is honored since 5.21.0) |\n| `maxValue` | number | Override auto-calculated max (skips `calculateAggregates`; `0` is honored since 5.21.0) |\n| `customFunction` | function | `(sprite, min, max, value)` — full control over the rule |\n\n**Using heat rules on bullets** — bullets need an explicit `am5.Template`, and the series must track the field the rule reads:\n\n```js\nvar circleTemplate = am5.Template.new({});\n\nseries.bullets.push(function(root, series, dataItem) {\n  return am5.Bullet.new(root, {\n    sprite: am5.Circle.new(root, {\n      fill: series.get(\"fill\"),\n      tooltipText: \"{valueX}: {valueY}\"\n    }, circleTemplate)              // pass template as 3rd arg\n  });\n});\n\nseries.set(\"heatRules\", [{\n  target: circleTemplate,\n  dataField: \"valueY\",\n  min: 3,\n  max: 25,\n  key: \"radius\"\n}]);\n```\n\nRules that make bullet heat rules work (each failure is **silent** — every bullet just comes out the same size):\n- `target` must be the **`Template`** the bullet sprites are built from (3rd argument of `am5.Circle.new(...)`), not the sprite and not `series.bullets`.\n- `dataField` is the data item **property key** (`\"valueY\"`, `\"valueX\"`, `\"value\"`, …), **not** the raw column name. To size XY bullets by a column that is not already an axis value, register it as the base value field: `series.set(\"valueField\", \"population\")` and use `dataField: \"value\"`.\n- `calculateAggregates: true` is required (unless `minValue`/`maxValue` are given) — without it `valueLow`/`valueHigh` are never computed and every bullet gets the midpoint size.\n- Setting `valueField` (or any `*Field`) **after** the series has processed data does not re-read the data — re-set it: `series.data.setAll(series.data.values.slice())`.\n- Bullet heat rules survive `ChartSerializer` (verified 5.21.0): the sample sprite the serializer builds from the factory is disposed right away and leaves the template, so the old `sprite._setDataItem(dataItem)` workaround is not needed.\n\n**HeatLegend:**\n\n```js\nvar heatLegend = chart.children.push(am5.HeatLegend.new(root, {\n  orientation: \"horizontal\",       // or \"vertical\"\n  startColor: am5.color(0xe5dc36),\n  endColor: am5.color(0x5faa46),\n  stepCount: 5                     // number of color stops\n}));\n\n// Sync legend range with series data: the end labels show these numbers\nseries.events.on(\"datavalidated\", function() {\n  heatLegend.set(\"startValue\", series.getPrivate(\"valueLow\"));\n  heatLegend.set(\"endValue\", series.getPrivate(\"valueHigh\"));\n});\n\n// Through several colors (5.21.2): `colors` in place of startColor/endColor, matching a heat rule's `stops`\nvar ic = root.interfaceColors;\nvar scaleLegend = chart.children.push(am5.HeatLegend.new(root, {\n  orientation: \"horizontal\",\n  colors: [ic.get(\"negative\"), ic.get(\"warning\"), ic.get(\"positive\")]\n  // stepCount: 1 (default) = a gradient through them; with stepCount > 1, one step per color\n}));\n```\n\n`startText`/`endText` replace the numbers at the ends: with `startText: \"Low\"` the label says only \"Low\", whatever `startValue` is, and `\"\"` leaves it blank. `{startValue}` in them is not filled in. Leave them out to show `startValue`/`endValue` as formatted numbers. On a map, give the legend a `background` so a zoomed map doesn't show through it (`references/map.md` → Choropleth). Docs: https://docs.amcharts.com/v5/concepts/legend/heat-legend/#startend-labels.\n\n## Animations\n\n```js\nseries.appear(1000);        // duration in ms\nchart.appear(1000, 100);    // duration, delay\n```\n\n**`autoAppear` (5.21.0)** — the same opening animation as a setting, so it works from a JSON config or `<am5-chart>`, where `appear()` cannot be called:\n\n```js\nchart.setAll({ autoAppear: true, appearDuration: 1000, appearDelay: 100 });\nseries.setAll({ autoAppear: true, appearDuration: 1000 });   // a series waits for its first data\n// JSON: \"settings\": { \"autoAppear\": true, \"appearDuration\": 1000, \"appearDelay\": 100 } on the chart and each series\n```\n\nIt plays once, when the element is first drawn (data updates do not replay it; turning the setting off and on does). `autoAppear` defaults to `false`; `appearDuration` falls back to the element's `stateAnimationDuration`; `appearDelay` (default `0`) keeps the element hidden until it starts. Elements made from a template play as each is made; an element that starts hidden stays hidden.\n\n**Declared animations — the `animations` setting (5.20.8).** Every element can carry its own animations as data, so they live in a JSON config and survive `ChartSerializer` — prefer this over `sprite.animate({ loops: Infinity })` for endless effects:\n\n```js\nseries.bullets.push(function (root, series, dataItem) {\n  return am5.Bullet.new(root, {\n    sprite: am5.Circle.new(root, {\n      radius: 6,\n      animations: [   // loops: 0 = forever; yoyo goes back to `from`; easing is a NAME\n        { key: \"scale\", from: 1, to: 1.6, duration: 800, loops: 0, yoyo: true, easing: \"sine\" },\n        { key: \"opacity\", from: 1, to: 0.3, duration: 800, loops: 0, yoyo: true }\n      ]\n    })\n  });\n});\n```\n\nEntry (`IDeclaredAnimation`) fields: `key`, `to`, `duration` (required; with `yoyo` one way), `from` (default: current value), `delay` (`0`), `loops` (`1`; `0` = forever), `yoyo` (`false`), `easing` (`\"linear\"` — one of the 8 names under \"Easing functions\"; unknown names silently become linear), `ease` (`\"in\"` default, `\"out\"`, `\"inOut\"`), `target` (`\"self\"` default, or `\"dataItem\"` for a data-item value such as a map point's `positionOnLine`). They start when set, restart when changed, stop on dispose. **Give `from` explicitly** unless the setting has a theme default (`scale`/`opacity`/`rotation` do; `dx`, `fill`, a data item's `positionOnLine` may not) — with `from` omitted and an `undefined` current value it jumps straight to `to`, no animation. In JSON, colors/percents in `from`/`to` are `{ \"type\": \"Color\", \"value\": \"#f00\" }` / `{ \"type\": \"Percent\", \"value\": 50 }`.\n\n## Events\n\n```js\n// Interaction events on elements\nseries.columns.template.events.on(\"click\", (ev) => {\n  console.log(\"Clicked:\", ev.target.dataItem.dataContext);\n});\n\n// Common events: click, pointerover, pointerout, pointerdown, globalpointermove\n\n// Series/chart lifecycle events\nseries.events.on(\"datavalidated\", () => {\n  // Fires after data is processed — safe to read dataItems\n});\n\n// Axis zoom/scroll — watch start/end settings, not events\nxAxis.on(\"start\", () => {\n  console.log(\"Zoomed/scrolled\");\n});\nxAxis.on(\"end\", () => {\n  console.log(\"Zoomed/scrolled\");\n});\n\n// Setting change watch\nsprite.on(\"width\", (width) => {\n  console.log(\"Width changed to\", width);\n});\n\n// One-time listener\nseries.events.once(\"datavalidated\", () => { /* runs once */ });\n\n// Remove listener\nconst disposer = sprite.events.on(\"click\", handler);\ndisposer.dispose(); // removes the listener\n```\n\n**Knowing when the chart has finished drawing.** There is no \"rendered\" event. `datavalidated` fires once the data is processed, and the next `frameended` can come long before drawing ends. With 5,000 bullets drawing ended about 5 times later than that `frameended`, and with 50,000 about 10 times later. amCharts draws only while something has changed or is animating, so two animation frames in a row without a `frameended` mean it is done. Call this right after the change (`data.setAll()`, a zoom, `selectPeriod()`):\n\n```js\nfunction whenRendered(root, callback) {\n  var frames = 0, seen = 0, quiet = 0;\n  var listener = root.events.on(\"frameended\", function () { frames++; });\n  (function check() {\n    requestAnimationFrame(function () {\n      if (frames === seen) quiet++; else { quiet = 0; seen = frames; }\n      if (quiet >= 2) { listener.dispose(); callback(); } else check();\n    });\n  })();\n}\nseries.data.setAll(data);\nwhenRendered(root, function () { /* everything is drawn */ });\n```\n\nWith `root.fps` set, frames are spaced `1000 / root.fps` ms apart, so wait longer than that instead of two animation frames. Endless animations (`loops: Infinity` with `animate()`, `loops: 0` in declared `animations`) never settle. Without a license, the amCharts logo fades in 3 s after the root is created and draws for 1.5 s; a check during that time waits for it.\n\n**Opening a link on click needs no handler (5.20.7):** `series.set(\"urlField\", \"url\")` makes each item's bullet, column, slice, Venn slice, map polygon or map line open the URL in its data row (`linkTarget`, default `\"_self\"`) — see \"Recent API changes\". Hierarchy nodes, flow nodes/links and word-cloud labels are not linked; keep a `click` handler there.\n\n**A tap fires no DOM `click` on a pannable chart.** On touch, a tap on an XYChart with `panX`/`panY`, under a cursor with a zoom or select `behavior`, or on a `draggable` sprite gives `pointerdown`/`pointerup` but no `mousedown`/`mouseup`/`click` on the page (Chrome touch emulation, 5.21.5). The amCharts `click` event still fires: use `events.on(\"click\", …)`, not a DOM listener.\n\n## Settings API\n\n```js\n// Set after creation\nsprite.set(\"fill\", am5.color(0xff0000));\nsprite.setAll({ fill: am5.color(0xff0000), strokeWidth: 2 });\n\n// Read current value\nconst fill = sprite.get(\"fill\");\nconst width = sprite.getPrivate(\"width\"); // read-only internal values\n\n// set() RETURNS the value — handy for capturing the created object inline:\nconst cursor = chart.set(\"cursor\", am5xy.XYCursor.new(root, {}));\n```\n\n**Reading back a `Percent`:** a `Percent` exposes two numbers — `.percent` is the 0–100 value, `.value` is the normalized 0–1 fraction. `am5.percent(50).percent === 50` but `am5.percent(50).value === 0.5`. When you read a percent setting back (e.g. `sprite.get(\"x\")` after setting `am5.percent(50)`), use `.percent` for a 0–100 number; `.value` gives `0.5`.\n\n**Reading animated settings is unreliable mid-animation.** Right after `series.appear()` / `chart.appear()`, animated settings like `opacity` are still transitioning — `get(\"opacity\")` can return `0` (the start value). Read such settings after the animation completes, or don't persist values read during appear (a common way to accidentally bake `opacity:0` into generated code).\n\n## Settings that already equal the default — omit them\n\nGenerated code routinely spells out settings that equal the amCharts default (verified against the default themes, and for `Gantt` the code, of 5.21.2). They add noise and mislead readers into thinking they matter. Do not emit these unless changing them:\n\n| Class | Setting(s) that are already the default |\n|-------|------------------------------------------|\n| All hierarchy series | `childDataField: \"children\"`, `downDepth: 1`, `initialDepth: 5` |\n| `Sunburst`, `Partition`, `Treemap`, `VoronoiTreemap` | `singleBranchOnly: true` (`Partition`/`Treemap` also `upDepth: 0`; `VoronoiTreemap` also `shapeType: \"polygon\"`; `Sunburst` ignores the setting since 5.21.0 — always single-branch) |\n| `Tree`, `ForceDirected` | `singleBranchOnly: false`, `upDepth: Infinity`, `topDepth: 0` (`Tree` also `orientation: \"vertical\"`) |\n| `PieSeries`, `FunnelSeries`, `PyramidSeries`, `PictorialStackedSeries` | `alignLabels: true` (`PieSeries` also `startAngle: -90`, `endAngle: 270`; `FunnelSeries` also `orientation: \"vertical\"`, `startLocation: 0`, `endLocation: 1`, `bottomRatio: 0`) |\n| `Chord` | `sort: \"none\"` (data order) |\n| `Gantt` | `excludeWeekends: true` |\n| `XYSeries` (all XY series) | `maskBullets: true` — note the default is **true**, so `maskBullets: false` is a real change |\n| `LineSeries` (incl. smoothed/step) | `connect: true`; `StepLineSeries` `noRisers: false` |\n| `XYChart` | `maxTooltipDistance` — leave **unset** (unset shows tooltips for all items in the category; `0` is *not* the same) |\n| `HeatLegend` | `stepCount: 1` |\n\nRuntime-mutated settings (`visible`, `x`/`y`, `opacity`, `scale`, cursor line `visible`, physics/random layouts, computed `AxisRendererCurve.points`) cannot be checked by \"remove and re-`get()`\" — amCharts rewrites them after render. User-set values live in `entity._userProperties` (what `ChartSerializer` reads), separate from the full `_settings` bag that includes theme and internal values.\n\n## Dynamic data\n\n```js\n// Replace all data (full redraw, NO animation)\nseries.data.setAll(newData);\n\n// Add items\nseries.data.push({ category: \"New\", value: 42 });\n\n// Update item at index — this ANIMATES the change\nseries.data.setIndex(0, { category: \"Updated\", value: 99 });\n\n// IMPORTANT: To update data WITH animation, use setIndex() per item.\n// setAll() replaces everything at once — no transition animation.\n// Loop through items for animated updates:\n// newData.forEach(function(item, i) { series.data.setIndex(i, item); });\n\n// Remove item at index\nseries.data.removeIndex(2);\n\n// Insert at specific position\nseries.data.insertIndex(1, { category: \"Inserted\", value: 50 });\n\n// Iterating dataItems — dataItems is a PLAIN ARRAY, not a List\n// ❌ series.dataItems.each(fn)                              — will throw, .each() does not exist\n// ✅ am5.array.each(series.dataItems, function(dataItem) {}) — amCharts array utility\n// ✅ series.dataItems.forEach(function(dataItem) {})         — standard JS\n```\n\n**Changing values on existing data items.** Series draw from the **working** values, so `dataItem.set(\"valueY\", v)` (or `\"value\"` on a pie) changes nothing on screen, and `markDirtyValues()` doesn't help. Change the data row with `series.data.setIndex(i, row)` (animates), or set the working key too (jumps; use it for per-frame updates):\n\n```js\nxySeries.dataItems[0].setAll({ valueX: 4, valueY: 7, valueXWorking: 4, valueYWorking: 7 });   // XY series\npieSeries.dataItems[0].setAll({ value: 80, valueWorking: 80 });                                // pie, funnel, pyramid\n// per-frame updates through setIndex on XY: set interpolationDuration: 0 on the series, or the points lag behind\n```\n\nOn maps it is worse: a `geometry` can't be animated, so with `setIndex` it switches only when `interpolationDuration` ends, and a line or polygon replaced every frame keeps its first shape. Set `interpolationDuration: 0`, or set the geometry on the element (`references/map.md` → \"Live updates\").\n\nA data item's bullets are a plain array **property**: `dataItem.bullets?.[0]?.get(\"sprite\")` is the sprite the bullet function made (`dataItem.get(\"bullets\")` is `undefined`).\n\n`dataItem.bullets` stays `undefined` until the series draws that item: right after `data.setAll()`, in `datavalidated` and in the first `frameended` (5.21.5: bullets appeared on the second frame), and, on a zoomed `DateAxis`, for items out of view. Decide a bullet's look inside the bullet function from `dataItem` (or with `templateField`), not by reaching into `dataItem.bullets` after setting the data.\n\n## Performance: big data, fast updates, no animation\n\n- **Animations off:** leave out the Animated theme. To keep it but stop one element animating, set `interpolationDuration: 0` (value changes, axis zoom and rescale) or `stateAnimationDuration: 0` (hover and show/hide states) on it. Docs: https://docs.amcharts.com/v5/concepts/animations/#turning-off-animations.\n- **Zoom without animation:** an axis zooms over its own `interpolationDuration` (600 ms with the Animated theme). There is no `zoomAnimation` setting. Set it to 0 on the X axis and on value axes, which also animate their rescale after a zoom. `zoom()`, `zoomToDates()`, `zoomToValues()` and `zoomToCategories()` take a duration as their third argument; `0` jumps. Docs: https://docs.amcharts.com/v5/charts/xy-chart/zoom-and-pan/#zoom-animation.\n- **Frame rate:** `root.fps = 30` redraws about 20 times a second instead of 60, which frees the main thread for incoming data.\n- **High-rate streams** (a point every 10 ms, 3 series):\n  - The Live Data pattern (`push` + `removeIndex(0)` per point, Animated theme) kept up with 30–60% of the points.\n  - `interpolationDuration: 0` on the series and axes, plus `root.fps = 30`, kept up with 80–90%.\n  - Collecting points and adding them once per frame with `data.pushAll()` adds little.\n  - A timer-driven feed drops the ticks a busy page skips; WebSocket messages queue instead.\n- **Large line data:** `references/xy.md`, \"DateAxis\". **Large scatter:** `references/xy.md`, \"Scatter / Bubble chart\". **Knowing when drawing has finished:** \"Events\".\n\n## Adapters\n\n```js\n// Dynamically modify a setting value before it's applied\nseries.columns.template.adapters.add(\"fill\", (fill, target) => {\n  return target.dataItem.get(\"valueY\") > 100\n    ? am5.color(0x00cc00)\n    : am5.color(0xcc0000);\n});\n\n// Adapter on axis labels\nxAxis.get(\"renderer\").labels.template.adapters.add(\"text\", (text, target) => {\n  return text + \"!\";\n});\n```\n\n## States\n\n```js\n// Hover state — applied automatically on pointer over\nseries.columns.template.states.create(\"hover\", {\n  fillOpacity: 0.8,\n  scale: 1.05\n});\n\n// Active state — toggled via click\nseries.columns.template.states.create(\"active\", {\n  fill: am5.color(0xff0000)\n});\n\n// Built-in state names: \"default\", \"hover\", \"active\", \"disabled\", \"hidden\"\n// State animation: stateAnimationDuration, stateAnimationEasing\n```\n\n**A state keeps the value it first replaced.** Once a state (e.g. `hover`) has changed a setting, the sprite's `\"default\"` state holds the value from that moment and restores it on every unhover. So a setting changed later (painting a polygon on click, a new base color) snaps back on the next unhover unless you change it in both places:\n\n```js\npolygon.set(\"fill\", color);\npolygon.states.lookup(\"default\")?.set(\"fill\", color);\n```\n\n**`sprite.hover()` also shows the sprite's tooltip.** To highlight other elements from an event (related links or columns), apply the state instead: `sprite.states.applyAnimate(\"hover\")`, and `\"default\"` to undo it. Several `hover()` calls move the shared tooltip to the last sprite.\n\n## Parameterized themes — Monochrome & Adaptive (5.20.0)\n\nTwo themes generate their palette from colors you pass in (OKLCH-based, so the result stays perceptually balanced). Because a theme cannot take constructor parameters, these ship as **factory functions** — call them with `(root, settings)`; `.new(root, settings)` also works.\n\n```js\nimport am5themes_Monochrome from \"@amcharts/amcharts5/themes/Monochrome\";\nimport am5themes_Adaptive from \"@amcharts/amcharts5/themes/Adaptive\";\n\n// Monochrome — single-hue lightness ramp\nroot.setThemes([\n  am5themes_Animated.new(root),\n  am5themes_ResponsiveMax.new(root),\n  am5themes_Monochrome(root, {\n    color: 0x2c6e91,   // base hue (default: blue #2e7c9e)\n    accent: 0xff7f0e,  // optional — applied to the FIRST series only, so it pops\n    count: 7,          // steps in the ramp (default 7)\n    dark: false        // true = dark background + light-to-mid ramp\n  })\n]);\n\n// Adaptive — full palette generated from one or two base colors\nroot.setThemes([\n  am5themes_Animated.new(root),\n  am5themes_ResponsiveMax.new(root),\n  am5themes_Adaptive(root, {\n    baseColor: 0x2c6e91,   // first generated color IS this color (good for brand colors), unless keepContrast has to move it\n    baseColor2: 0xffdd00,  // optional — palette spans the two colors\n    count: 10,             // number of series colors (default 10)\n    dark: false\n  })\n]);\n```\n\nBoth are additive (they do not modify built-in themes) and both handle dark mode themselves via `dark: true` — do not also add the `Dark` theme.\n\n**More settings (5.21.2, both themes, all off by default):** `interleave: true` takes the colors in the order 1, 4, 2, 5, 3, 6, so series next to each other differ more (Monochrome keeps `accent` first); `mapShade: true` fills map land with a mid shade of the base color, as light as default map land, instead of the color itself; `keepContrast: true` keeps the series colors and primary buttons at least 3:1 against the background (or give a ratio, e.g. `4.5`). In Adaptive it moves `baseColor` and `baseColor2` themselves, so the first color is then not exactly the brand color; in Monochrome it moves the end of the shades nearest the background. A branded palette:\n\n```js\nam5themes_Adaptive(root, { baseColor: 0x2c6e91, baseColor2: 0xffdd00, count: 10, interleave: true, mapShade: true, keepContrast: true })\n```\n\n## Custom themes\n\n```js\nconst myTheme = am5.Theme.new(root);\nmyTheme.rule(\"Label\").setAll({ fontSize: 12, fill: am5.color(0x555555) });\nmyTheme.rule(\"Grid\").setAll({ stroke: am5.color(0xe0e0e0) });\nroot.setThemes([am5themes_Animated.new(root), am5themes_ResponsiveMax.new(root), myTheme]);\n// Theme order matters: later themes override earlier ones\n```\n\n## Dark theme\n\nWhen the page has a dark background, add the Dark theme so labels, grid, and tooltips are readable:\n\n```js\nroot.setThemes([\n  am5themes_Animated.new(root),\n  am5themes_ResponsiveMax.new(root),\n  am5themes_Dark.new(root)        // must come after Animated and ResponsiveMax\n]);\n```\n\nImport: `import am5themes_Dark from \"@amcharts/amcharts5/themes/Dark\"` or CDN `themes/Dark.js`.\n\n**Rule:** Only add Dark theme when the background is clearly dark. Default to white/light background with no Dark theme.\n\n## ColorSet — using default colors\n\namCharts assigns colors automatically via a built-in ColorSet. Do not invent custom palettes unless the user asks.\n\n```js\n// Get the chart's default color set\nvar colors = chart.get(\"colors\");       // XY and Radar charts only (pie and other percent charts: series.get(\"colors\"))\nvar colors = series.get(\"colors\");      // pie/percent charts use series-level colors\n\n// MapChart has NO built-in ColorSet — create your own:\nvar colors = am5.ColorSet.new(root, {});\n\n// Get a specific color by index (does not advance internal counter)\nvar color = colors.getIndex(0);         // first default color\nvar color = colors.getIndex(3);         // fourth default color\n\n// Get next color in sequence (advances internal counter)\nvar color = colors.next();\n\n// Reset counter back to start\ncolors.reset();\n\n// Override the default palette (only if user requests specific colors)\ncolors.set(\"colors\", [\n  am5.color(0x095256),\n  am5.color(0x087f8c),\n  am5.color(0x5aaa95)\n]);\n```\n\n**Swapping a `ColorSet`.** The theme's `baseColor` resolves lazily, so a **synchronous** re-color right after swapping a `ColorSet` can read a transient value (sprites momentarily black). Re-set the series data and let amCharts' own data pass recolor the sprites. Before 5.22.0, `colorSet.set(\"colors\", [])` crashed the next `next()`/`getIndex()`. Since 5.22.0 an empty list starts from `baseColor`.\n\n**`step` with a theme that reuses its colors** (`reuse: true`: Adaptive, Monochrome, Nord, Pastel, Kelly, …): before 5.21.2 a `step` sharing a factor with the list length used only a few of the colors (a word cloud or treemap with Nord got two or three). Now every color is used before any repeats, so `step: count / 2` interleaves the palette.\n\n**Repeats are lighter (5.21.3).** In themes that reuse their list, once every color has been used, the next round is 10% lighter instead of the same colors again. This covers Adaptive, Monochrome, Ember, Frozen, Kelly, Material, Midnight, Moonrise, Nord, Pastel, Petroleum, Savanna and Spirited, with their Dark variants, but not Colorblind, Patterns or Dataviz. The setting is `repeatLightness` on the `ColorSet`: HSL lightness per round, `0.1` is 10%, and a negative value makes it darker. It only acts with `reuse: true`. The color sets of one root share the theme's list, and the repeats are added to that list, so whichever color set on the root first needs a new round decides that round for every chart on it. To repeat the colors as they are, as before 5.21.3, set it for the whole root:\n\n```js\n// Every ColorSet on the root, through a theme rule\nvar noLighter = am5.Theme.new(root);\nnoLighter.rule(\"ColorSet\").set(\"repeatLightness\", 0);\nroot.setThemes([am5themes_Animated.new(root), am5themes_ResponsiveMax.new(root), am5themes_Nord.new(root), noLighter]);\n\n// Adaptive and Monochrome: a theme setting (true = 0.1, or a number)\nam5themes_Adaptive.new(root, { repeatLightness: false });\n```\n\nWith one chart on the root, `chart.get(\"colors\").set(\"repeatLightness\", 0)` before the data is set works too.\n\n**Three or more series.** Smallest color difference (CIEDE2000) among the first 4 / 6 series colors, 5.21.5; higher is easier to tell apart:\n\n| Choice | First 4 / 6 | Note |\n|---|---|---|\n| default | 6.3 / 6.3 | blue to violet, 18° apart |\n| `chart.get(\"colors\").set(\"step\", 3)` | 19.1 / 19.1 | keeps the default look |\n| `Colorblind` | 21.7 / 21.7 | Okabe-Ito; the 4th color is a pale yellow |\n| `Kelly` | 22.8 / 17.0 | the 1st color is yellow, the weakest on white |\n| `Nord` | 22.1 / 14.2 | |\n\nAvoid these for many series: `Dataviz` (series 1 and 5 are the same navy: 4.0), `Frozen` (6.9), `Moonrise` (9.4), `Spirited` (10.2), `Material` (10.3). For lines, also set `strokeWidths: [2]` on the XYChart (the legend line follows) and `legend.markers.template.setAll({ width: 24, height: 14 })`.\n\n## Data processor\n\n```js\n// Auto-convert fields when loading external / API data\nseries.data.processor = am5.DataProcessor.new(root, {\n  dateFields: [\"date\"],\n  dateFormat: \"yyyy-MM-dd\",  // read as local time (UTC with root.utc); see below for leaving it out\n  numericFields: [\"value\", \"count\"],\n  colorFields: [\"color\"],\n  emptyAs: 0  // replace null, undefined and \"\" with 0 (before 5.21.0 it also replaced 0 and false)\n});\n// Configure processor BEFORE setting data\n```\n\nWithout `dateFormat`, since 5.21.1 the browser's `Date` parses the strings, so ISO strings work and a date-only `\"2024-03-15\"` is midnight **UTC**. Before 5.21.1 every such string became 1 January 1970.\n\n## Serializing to JSON (ChartSerializer / JsonParser)\n\n**To write a config by hand** (a \"JSON config\", `<am5-chart>`, a framework package's `config` prop, a Chart Maker link), read `references/json.md`. It covers the exact format, with a complete config per chart family. A config is not `{ \"chart\": …, \"series\": … }`; every object has `\"type\"`, its options go in `\"settings\"`, and its parts and data go in `\"properties\"`.\n\n`am5plugins_json.ChartSerializer` turns a live chart into a JSON config and `am5plugins_json.JsonParser` rebuilds it (`await parser.parse(config, { parent: root.container })`). Rules that keep round-trips working:\n\n- **Serialize the chart's top-level container child:** `serializer.serializeAll(root.container.children.getIndex(0))` — the chart, or on chart-less types (hierarchy, flow, word cloud, Venn) the series itself. Before 5.21.0 a series placed straight in `root.container`, or one whose `selectedDataItem` points back at itself, overflowed the stack (`Maximum call stack size exceeded`) or broke `JSON.stringify`; 5.21.0 serializes them. A drilled-down hierarchy's `selectedDataItem` is still not restored (it is written as `\"@self.dataItems.-1\"`).\n- **Adapters do not round-trip.** `includeAdapters` (default `true`) writes each adapter as `{ key, callback: \"function (…) {…}\" }`; the parser does not turn that string back into a function (and the closure's `chart`/`series`/`root` would not exist anyway). Before 5.20.4 the string was registered as a callback and crashed the chart (`i[s] is not a function` in `Entity.fold`); since 5.20.4 such adapters are skipped. Either way the effect is lost — replace palette-coloring adapters with declarative equivalents: `colorByDataItem: true` on column series (5.20.4), a per-item `fill` data field + `templateField`, or `heatRules`.\n- **Only user-set settings are serialized (5.20.3)** — theme and library defaults are left out, so a serialized config is much smaller than before and a value you never set will not appear in it. Add `includeRoot: true` (5.20.2) to also write a top-level `root` section (Root settings/properties, `interfaceColors`, formatters). Since 5.22.0 a parsed `root` section sets only those properties and a named locale, and never turns `sanitizeHTML` off, unless parsed with `trusted: true` (`references/json.md` rule 9).\n- **Re-parsing into an existing chart:** `parser.parse(config, { updateTargets: \"soft\" })` (5.20.3) applies settings onto an existing object of the same `type` instead of replacing it. The default `\"strict\"` replaces.\n- **Maps and locales with npm imports (5.21.4):** a geodata pack or locale that isn't a global is copied into the config whole, about 250 KB for `worldLow`, unless the serializer gets it in `resources`. `am5plugins_json.ChartSerializer.new(root, { resources: { am5geodata_worldLow } })` writes `\"geoJSON\": \"am5geodata_worldLow\"` instead; parse it back with the same `resources` (`references/json.md`, rule 8). With script tags the packs are globals and are written by name without it.\n- **Also saved (5.20.6 – 5.20.8):** `themeTags` you pass to `.new()` (5.20.6 — e.g. a `Button` with `themeTags: [\"switch\"]` keeps its look; tags the library adds are left out); a legend inside an `axisHeader` (5.20.7); declared `animations` (5.20.8, see \"Animations\"); and animations started in code that **loop forever** (`loops: Infinity`) with a nameable `am5.ease` easing — written as `animations` entries. `runningAnimations` (5.20.8, default `true`) controls the latter: `am5plugins_json.ChartSerializer.new(root, { runningAnimations: false })` turns it off. Never saved: finite animations (`appear()`, states, zoom) and loops with a custom-function or `pow` easing — for the opening animation use `autoAppear` (5.21.0, see \"Animations\").\n- **Data-item loops (5.21.0):** a loop started on a **data item** in code (`dataItem.animate({ key: \"positionOnLine\", loops: Infinity, … })`) is saved as an `animations` entry with `target: \"dataItem\"`. When every data item plays the same loop, it goes on the bullet sprite. Since 5.21.3, when they differ (e.g. points each moving at their own speed), each one goes in its own data row, under the sprite's `templateField` (`\"bulletSettings\"` if none is set). Before 5.21.3, every item got the first one's loop.\n- **Also saved (5.21.0):** a series hidden with `hide()` or a legend click; elements you add to library-built containers (`chart.plotContainer`, `seriesContainer`, axes containers, an axis) — no `themeTags: [\"serialize\"]` needed; a `ZoomableContainer`'s `contents`; `Date` values (as timestamps); settings on a series' `bulletsContainer` and on a pie/funnel series' `labelsContainer`/`ticksContainer`; the `axisFills`, `rectangles` (`Treemap`, `Partition`) and `polygons` (`VoronoiTreemap`) templates. A color taken from `root.interfaceColors` is written as a reference, `\"@root.interfaceColors.get('background')\"`, so a config parsed under another theme (e.g. Dark) uses that theme's color — write the same string in hand-made configs. Since 5.21.3 a color taken from the theme's palette with `getIndex()` is written as `\"@colors.getIndex(3)\"` the same way, and hand-made configs can use it too in settings (e.g. `\"fill\": \"@colors.getIndex(0)\"`). Only the palette's own colors become references: generated or lightened repeats stay hex, and references are not read inside data rows. Changing a setting such as `step` on a chart's colors no longer writes the theme's whole palette into the config.\n- **Not captured by `ChartSerializer` (as of 5.21.0)** — re-apply these in code after `parse()`: a `ZoomTools` you added to a hand-made `ZoomableContainer` (its `target` is written as a copy, so the parsed buttons drive a different container — re-point `target`, or use `am5.SerialChartContainer`, which wires its own `zoomTools`); Venn `hoverGraphics` (Venn slice-template `states` do round-trip); data items added with `pushDataItem()` (only `series.data` rows are written — map points on lines can be data rows since 5.20.6, see `references/map.md`).\n- **Bullets** are captured by calling the factory with a sample data item — write factories as `function(root, series, dataItem)` (pitfall #36).\n\n**`<am5-chart>` — a chart as an HTML element (5.21.0).** Builds a chart from a JSON config with no root or chart code. With script tags, load `index.js`, `plugins/json.js`, `element.js`, then every chart package the config uses; with npm, `import { defineChartElement } from \"@amcharts/amcharts5/element\"` and call `defineChartElement()`, which does nothing if the element already exists. A bare `import \"@amcharts/amcharts5/element\"` also works from 5.21.5; before that, esbuild dropped it and the element was never defined. Chart packages are loaded on demand. Then set `element.themes = [am5themes_Animated, am5themes_ResponsiveMax]`, for a map `element.resources = { am5geodata_worldLow }` (5.21.4), and `element.config = {…}`, as properties:\n\n```html\n<script src=\"https://cdn.amcharts.com/lib/5/index.js\"></script>\n<script src=\"https://cdn.amcharts.com/lib/5/plugins/json.js\"></script>\n<script src=\"https://cdn.amcharts.com/lib/5/element.js\"></script>\n<script src=\"https://cdn.amcharts.com/lib/5/percent.js\"></script>\n<script src=\"https://cdn.amcharts.com/lib/5/themes/Animated.js\"></script>\n<script src=\"https://cdn.amcharts.com/lib/5/themes/ResponsiveMax.js\"></script>\n\n<am5-chart themes=\"Animated ResponsiveMax\" renderer=\"svg\" style=\"height: 400px\" config='{\n  \"type\": \"PieChart\",\n  \"properties\": { \"series\": [{ \"type\": \"PieSeries\",\n    \"settings\": { \"valueField\": \"value\", \"categoryField\": \"category\", \"autoAppear\": true },\n    \"properties\": { \"data\": [{ \"category\": \"A\", \"value\": 10 }, { \"category\": \"B\", \"value\": 6 }] } }] }\n}'></am5-chart>\n\n<script>\ndocument.querySelector(\"am5-chart\").whenReady().then(function (r) {\n  // r.root, r.chart — or listen for the element's \"ready\" / \"error\" events\n});\n</script>\n```\n\nAttributes: `config` (JSON) or `src` (URL of a JSON file), `themes`, `renderer=\"svg\"` (default canvas). The `themes` attribute takes names, space- or comma-separated, or since 5.21.4 JSON with a theme's settings: `themes='[\"Animated\", \"ResponsiveMax\", [\"Adaptive\", { \"baseColor\": \"#4150a0\" }]]'`. It works with script tags only. With npm, the `themes` property takes theme classes, e.g. `[am5themes_Animated, am5themes_ResponsiveMax]`, or since 5.21.4 a class with its settings: `[am5themes_Animated, am5themes_ResponsiveMax, [am5themes_Adaptive, { baseColor: \"#4150a0\" }]]`. Without a height from CSS or its parent it is 400 px high. Themes are not part of a config. Changing `config`/`themes` rebuilds the chart; removing the element disposes it.\n\n## Accessibility\n\n```js\nseries.columns.template.setAll({\n  focusable: true,\n  ariaLabel: \"{categoryX}: {valueY}\",\n  role: \"figure\"\n});\n// Keyboard: TAB to navigate focusable elements, ENTER to click\n// focusableGroup: \"series1\" — TAB to first, arrows within group\n```\n\n**High contrast (5.21.0):** in a forced-colors mode such as Windows High Contrast, labels, grid, axes and buttons take the system colors so they stay visible; series colors are kept. It is on by default — `am5.Root.new(\"chartdiv\", { forcedColors: false })` keeps the chart's own interface colors.\n\nKeyboard/screen-reader behavior in 5.21.0: a `focusableGroup` is one TAB stop; arrow keys move between its members even when they are draggable (flow and hierarchy nodes) and SHIFT + arrows drag them; ESC hides a focused element's tooltip and ends a keyboard drag; SPACE clicks a focused element with a button-like `role`. New `ariaExpanded` setting (set by the library on Gantt tasks with subtasks and on hierarchy nodes with children); a `role: \"button\"` with `toggleKey` exposes `aria-pressed`. `am5.Modal` is a dialog to screen readers, named by its new `ariaLabel` setting (else its first heading).\n\n## Container & Layout\n\n```js\n// Containers organize child elements\nconst container = root.container.children.push(am5.Container.new(root, {\n  width: am5.percent(100),\n  height: am5.percent(100),\n  layout: root.verticalLayout  // also: horizontalLayout, gridLayout\n}));\n\n// Padding and margin\ncontainer.setAll({\n  paddingTop: 10,\n  paddingBottom: 10,\n  marginLeft: 20\n});\n```\n\n**Layout options:**\n\n| Layout | Access | Behavior |\n|--------|--------|----------|\n| Vertical | `root.verticalLayout` | Children stacked top-to-bottom |\n| Horizontal | `root.horizontalLayout` | Children in a row left-to-right |\n| Grid | `root.gridLayout` | Multi-column grid |\n| Custom grid | `am5.GridLayout.new(root, { maxColumns: 3 })` | Grid with custom column count |\n| None | omit `layout` | Children placed at x/y coordinates |\n\nUse layouts to arrange charts, legends, controls, and labels within containers.\n\n**Right to left: `direction: \"rtl\"` (5.22.0).** On a container with a horizontal or grid layout, it places the children from right to left, as a mirror image: a child's `marginLeft` ends up on its right. Rows of a grid still go top to bottom. In a vertical layout, children with no `x` of their own line up on the right. For a right-to-left language, set the Root's `direction` instead, which also turns the text and lays out the legends (see \"Legend\"). `reverseChildren: true` only reverses the order, so a grid starts at the bottom row; don't use it for RTL.\n\n## UI Elements\n\namCharts 5 provides built-in interactive UI widgets. **Prefer these over HTML elements** when building controls, unless instructed otherwise. Read `references/ui-elements.md` for full API and examples.\n\n| Element | Class | Description |\n|---------|-------|-------------|\n| Button | `am5.Button` | Clickable button with label, icon, background, hover/down/active states |\n| Slider | `am5.Slider` | Single-value slider (0-1 range), fires `rangechanged` event |\n| Scrollbar | `am5.Scrollbar` | Two-grip range selector, `orientation: \"horizontal\"\\|\"vertical\"` |\n| NumericStepper | `am5.NumericStepper` | Number input with up/down arrows |\n| ProgressPie | `am5.ProgressPie` | Circular progress indicator with `value`, `radius`, `innerRadius` |\n| SpriteResizer | `am5.SpriteResizer` | Drag-to-resize handles on any sprite |\n| EditableLabel | `am5.EditableLabel` | Label that becomes editable text field on click |\n| Modal | `am5.Modal` | HTML overlay dialog with `open()`/`close()` |\n| ColorPicker | `am5plugins_colorPicker.ColorPicker` | Color picker (requires `plugins/colorPicker.js`) |\n\n**Quick example — slider + button controlling a chart:**\n\n```js\n// Slider to control a value\nvar slider = container.children.push(am5.Slider.new(root, {\n  orientation: \"horizontal\",\n  start: 0.5,\n  width: am5.percent(80),\n  centerX: am5.percent(50),\n  x: am5.percent(50)\n}));\nslider.events.on(\"rangechanged\", function(ev) {\n  var value = ev.start;  // 0-1 range\n  // update chart based on slider position\n});\n\n// Button\nvar button = container.children.push(am5.Button.new(root, {\n  label: am5.Label.new(root, { text: \"Reset\" }),\n  centerX: am5.percent(50),\n  x: am5.percent(50)\n}));\nbutton.events.on(\"click\", function() {\n  slider.set(\"start\", 0.5);\n});\n```\n\n## Frameworks (React, Vue, Angular, Svelte, React Native)\n\nIn a framework app, use amCharts' package for that framework instead of writing the mount and dispose code yourself. The packages were first released on 2026-10-22; the current ones are react 5.0.1, vue 5.0.2, angular 5.0.1, svelte 5.0.3 (2026-10-23) and react-native 5.0.3, which loads amCharts 5.22.0. Each package makes the chart once its element is on the page, disposes it with the component, and loads the library in the browser only, so pages rendered on a server work (Next.js, Nuxt, SvelteKit, Angular SSR). Each takes a chart written in code, or a chart from a JSON config (it wraps the `<am5-chart>` element, see \"Serializing to JSON\").\n\n| Framework | Package | A chart in code | A chart from a JSON config |\n|---|---|---|---|\n| React 18+ (Next.js, React Router, Astro) | `@amcharts/amcharts5-react` | `const { ref, root, result } = useAmChart((root) => { … }, [data])`, `<div ref={ref} style={{ height: \"500px\" }} />` | `<AmChart config={config} themes={[am5themes_Animated, am5themes_ResponsiveMax]} onReady={({ root, chart }) => …} />` |\n| Vue 3.5.2+ (Nuxt) | `@amcharts/amcharts5-vue` | `const { root, result } = useAmChart(useTemplateRef(\"chart\"), (root) => { … }, { watch: () => props.data })`, `<div ref=\"chart\" style=\"height: 500px\">`; `root`/`result` are shallow refs | `<AmChart :config=\"config\" :themes=\"themes\" @ready=\"onReady\" />` |\n| Angular 19+ | `@amcharts/amcharts5-angular` | `AmChartDirective`: `<div [amChart]=\"buildChart\" [amChartDeps]=\"[data()]\" (amChartReady)=\"…\" style=\"height: 500px\">`, with `buildChart = (root: Root) => { … }` as an arrow-function property so `this` is the component | `AmChartComponent`: `<am5-chart [config]=\"config\" [themes]=\"themes\" (amChartReady)=\"…\">` |\n| Svelte 4+ (SvelteKit) | `@amcharts/amcharts5-svelte` | Svelte 5.29+: `<div {@attach attachAmChart(buildChart)} style=\"height: 500px\">`; Svelte 4 and older 5: `<div use:amChart={{ setup: buildChart, deps: [data] }}>` | `<am5-chart {@attach attachAmChartConfig({ config, themes })}>`, or `use:amChartConfig={{ config, themes }}`; events `onready`/`onerror` (`on:ready` in Svelte 4) |\n| React Native 0.72+ | `@amcharts/amcharts5-react-native` (+ `react-native-webview` 13+) | `<AmChart code={code} data={data} />`, where `code` is a **string** (below) | `<AmChart config={config} themes={[\"Animated\", \"ResponsiveMax\"]} />` |\n\nInstall the library with the package: `npm install @amcharts/amcharts5 @amcharts/amcharts5-react`. The current web packages need amCharts 5.21.4 or later (peer dependency `^5.21.4`); 5.0.0 worked with 5.21.0 and later. React Native installs only `@amcharts/amcharts5-react-native react-native-webview`: the WebView loads the library from the amCharts CDN.\n\n```jsx\n// React. Vue, Angular and Svelte work the same way: your function gets the root.\nimport { useEffect } from \"react\";\nimport { useAmChart } from \"@amcharts/amcharts5-react\";\nimport * as am5xy from \"@amcharts/amcharts5/xy\";\nimport am5themes_Animated from \"@amcharts/amcharts5/themes/Animated\";\nimport am5themes_ResponsiveMax from \"@amcharts/amcharts5/themes/ResponsiveMax\";\n\nfunction Chart({ data }) {\n  const { ref, result } = useAmChart((root) => {\n    root.setThemes([am5themes_Animated.new(root), am5themes_ResponsiveMax.new(root)]);\n    const chart = root.container.children.push(am5xy.XYChart.new(root, {}));\n    const xAxis = chart.xAxes.push(am5xy.CategoryAxis.new(root, {\n      categoryField: \"category\",\n      renderer: am5xy.AxisRendererX.new(root, {})\n    }));\n    const yAxis = chart.yAxes.push(am5xy.ValueAxis.new(root, {\n      renderer: am5xy.AxisRendererY.new(root, {})\n    }));\n    const series = chart.series.push(am5xy.ColumnSeries.new(root, {\n      xAxis: xAxis, yAxis: yAxis, categoryXField: \"category\", valueYField: \"value\"\n    }));\n    return { xAxis, series };\n  }, []); // made once: [data] here would make the chart again on every change\n\n  // New data goes to the chart that is there, with an animation\n  useEffect(() => {\n    if (result) {\n      result.xAxis.data.setAll(data);\n      result.series.data.setAll(data);\n    }\n  }, [result, data]);\n\n  return <div ref={ref} style={{ width: \"100%\", height: \"500px\" }}></div>;\n}\n```\n\n- **Your function gets the root:** never call `am5.Root.new()` or `root.dispose()` in it, because the package does both. Put the code that follows `Root.new()` in any example inside it.\n- **The chart's element needs a height.** The JSON-config components are 400 px high without one.\n- **Deps make the chart again from scratch:** `[data]` in React, `watch` in Vue (what Vue's `watch()` takes; add `deep: true` to also catch `push()`), `[amChartDeps]` in Angular, `deps` in Svelte actions. A Svelte attachment runs again when state read in its own expression changes. To change data without rebuilding, return what you need and use it from `result` (React, Vue), from `(amChartReady)`'s `{ root, result }` (Angular), or from a `$state.raw` variable set in the function (Svelte).\n- **SVG:** `useAmChart(setup, deps, { renderer: \"svg\" })` in React, `{ renderer: \"svg\" }` in Vue's options, `[amChartRenderer]=\"'svg'\"` in Angular, and `attachAmChart(setup, { renderer: \"svg\" })` or `renderer: \"svg\"` in Svelte's action parameter. The JSON-config components take a `renderer` prop or input.\n- **Themes for the JSON-config components are classes** (`[am5themes_Animated, am5themes_ResponsiveMax]`, not `.new(root)`): themes are not part of a config. A theme with its settings is a pair (5.21.4): `[am5themes_Animated, am5themes_ResponsiveMax, [am5themes_Adaptive, { baseColor: \"#4150a0\" }]]`. React Native takes theme **names** (`[\"Animated\", \"ResponsiveMax\", \"Dark\"]`), and the pair as `[\"Adaptive\", { baseColor: \"#4150a0\" }]`.\n- **Maps and locales in a JSON config** (5.21.4): the config names its geodata (`\"geoJSON\": \"am5geodata_worldLow\"`) and locale (`\"am5locales_de_DE\"`), and with npm imports those aren't globals, so pass them in the `resources` prop: `<AmChart config={config} resources={{ am5geodata_worldLow }} />` in React (import it from `@amcharts/amcharts5-geodata/worldLow`), `:resources` in Vue, `[resources]` in Angular, and `resources` in Svelte's `attachAmChartConfig({ config, resources })` / `use:amChartConfig`. Without it the map is blank, with a console warning that names the pack. React Native loads the geodata a config names by itself, but not a locale: give it `modules={[\"locales/de_DE\"]}`.\n- **Give amCharts plain data.** In Vue, keep amCharts objects out of reactive state: use `shallowRef()` for data, or pass `toRaw(data)`. In Svelte 5, use `$state.snapshot(data)`.\n- **License:** call `am5.addLicense(\"AM5C-…\")` once when the app starts, before any chart is made, never in the setup function, because the logo is decided when the root is made. Put it in `main.ts`/`main.jsx`, before `createApp()` or `bootstrapApplication()`. In Next.js, put it at the top of a client component's file; in Nuxt, in a client plugin (`plugins/amcharts.client.ts`); in SvelteKit, in `src/hooks.client.ts`. React Native takes `licenses={[\"AM5C-…\"]}` on each chart.\n- **Errors** thrown in your function go to React's nearest error boundary, Vue's `app.config.errorHandler`, Angular's `ErrorHandler` and `(amChartError)`, and Svelte's `onError` option (an uncaught error without it).\n- **Server rendering:**\n  - Next.js, Nuxt (no `<ClientOnly>` needed), SvelteKit and Angular SSR need no configuration.\n  - In the Next.js app router, `useAmChart` and theme classes need a client component (`\"use client\"`). A server component can render `<AmChart config={config}>` itself, because a config is plain data.\n  - React Router (Remix 2) and Astro: add `ssr: { noExternal: [\"@amcharts/amcharts5\"] }` to the Vite config (under `vite` in `astro.config.mjs`).\n  - Remix 3 has no package. Either load the script files and render `<am5-chart config={JSON.stringify(config)} data-rmx-preserve-dom>`, or use a `clientEntry()` component that imports amCharts inside Remix's `ref` mixin and disposes the root when its signal aborts.\n- **Unit tests in jsdom** (no canvas): mock the package, e.g. `vi.mock(\"@amcharts/amcharts5-react\", () => ({ useAmChart: () => ({ ref: () => {}, root: undefined, result: undefined }), AmChart: () => null }))`.\n\n**React Native** draws the real library in a WebView, so every chart type works, and it runs in Expo Go.\n- The chart code is a **string** written like a script-tag example: `am5xy.XYChart`, globals rather than imports. `root`, `data` (the `data` prop) and `post(name, value)` are in scope, and the files the code uses are loaded for it.\n- If the code returns a function, new `data` (compared by content) goes to that function instead of making the chart again.\n- `post()` calls the `onMessage(name, value)` prop.\n- Everything between the app and the chart is JSON, so give dates as timestamps.\n- Never build `code` from text a user typed or a server sent: pass such values in `data`.\n- Other props: `renderer`, `modules` (e.g. `[\"locales/de_DE\"]`), `libraryUrl`, `geodataUrl`, `onReady`, `onError`, `webViewProps`. A ref gives `run(code)`.\n\n```jsx\nimport { AmChart } from \"@amcharts/amcharts5-react-native\";\n\nconst code = `\nconst chart = root.container.children.push(am5xy.XYChart.new(root, {}));\n// ... axes and series, as in a script-tag example\nseries.columns.template.events.on(\"click\", (ev) => post(\"country\", ev.target.dataItem.dataContext.country));\nxAxis.data.setAll(data);\nseries.data.setAll(data);\nreturn (newData) => { xAxis.data.setAll(newData); series.data.setAll(newData); };\n`;\n\n<AmChart code={code} data={visits} themes={[\"Animated\", \"ResponsiveMax\"]} style={{ height: 300 }}\n  onMessage={(name, value) => console.log(name, value)} />\n```\n\n**Without a package** (an older framework version, or when the user asks for it), create the root once the element exists, and dispose it when the component goes away:\n\n```js\n// React\nuseLayoutEffect(() => {\n  const root = am5.Root.new(chartdiv.current); // const chartdiv = useRef(null)\n  // ... build chart\n  return () => { root.dispose(); };\n}, []);\n\n// Angular: in ngAfterViewInit, only if isPlatformBrowser(), inside zone.runOutsideAngular()\nngOnDestroy() { this.root?.dispose(); }\n\n// Vue: root = am5.Root.new(chartdiv.value) in onMounted, kept in a plain variable, not reactive state\nonBeforeUnmount(() => { root?.dispose(); });\n\n// Svelte: onMount runs in the browser only\nonMount(() => { const root = am5.Root.new(chartdiv); /* ... */ return () => root.dispose(); });\n```\n\n**Always call `root.dispose()`** — this cleans up all children, series, and event listeners.\n\n## v4 → v5 migration pitfalls\n\n| v4 pattern (WRONG) | v5 equivalent (CORRECT) |\n|-----------|--------------|\n| `am4core.create(\"div\", am4charts.XYChart)` | `am5.Root.new(\"div\")` + `am5xy.XYChart.new(root, {})` |\n| `new am4charts.LineSeries()` | `am5xy.LineSeries.new(root, {})` |\n| `series.dataFields.valueY = \"val\"` | `valueYField: \"val\"` in `.new()` settings |\n| `chart.data = [...]` | `series.data.setAll([...])` |\n| `am4core.color(\"#f00\")` | `am5.color(0xff0000)` |\n| `am4core.percent(50)` | `am5.percent(50)` |\n| `chart.dispose()` | `root.dispose()` |\n| `chart.legend = new am4charts.Legend()` | `chart.children.push(am5.Legend.new(root, {}))` |\n\n## Common pitfalls\n\n1. **Using `new` keyword** — always use `.new()` factory.\n2. **Forgetting `CategoryAxis.data.setAll()`** — axis will be empty.\n3. **Passing Date objects to DateAxis** — must be timestamps (ms).\n4. **Missing axis renderer** — every axis needs `renderer: am5xy.AxisRendererX.new(root, {})`.\n5. **Setting data before configuration** — configure everything, then set data last.\n6. **Raw hex strings for colors** — use `am5.color()`.\n7. **Mixing v4 and v5 API** — they are completely incompatible.\n8. **Calling `chart.dispose()` instead of `root.dispose()`** — always dispose root.\n9. **Using CSS to style chart elements** — amCharts draws on canvas by default; even with `am5.SVGRenderer` (5.21.0) its shapes have no per-element classes, are rewritten on redraw, and exports ignore page CSS. Style through settings, templates and themes.\n10. **Wrong package import** — check the package map table above.\n11. **Calling `.each()` on `dataItems`** — `series.dataItems` is a plain array, not an amCharts `List`. Use `am5.array.each(series.dataItems, fn)` or standard `forEach`/`for` loops. Only `series.data` (the `ListData` object) has `.each()`.\n12. **CDN script load order** — `index.js` must load first, then `xy.js`, then any package that depends on it (`radar.js`, `timeline.js`, `gantt.js`). Wrong order causes runtime errors. Correct order: `index.js`, `xy.js`, then `radar.js` / `timeline.js` / `gantt.js`, then `themes/*.js`. Gantt also needs `plugins/colorPicker.js` before `gantt.js`, or `am5gantt` is undefined. From an npm CDN (5.22.0+) the order and file names are the same under `…/@amcharts/amcharts5@<version>/dist/`; load every file from one pinned version.\n13. **No `minorGrid` / `minorTicks` / `minorLabels` objects** — These do not exist on axes. Minor grid is enabled via boolean flags on the **renderer**: `minorGridEnabled: true` and optionally `minorLabelsEnabled: true`. Styling is done through theme rules targeting the `\"minor\"` tag, not through separate object properties.\n14. **Flow chart animated bullets go on `series.bullets`, NOT `series.links.template.bullets`** — To animate labels/circles flowing along Sankey or Chord links, use `series.bullets.push(function(...) { ... })`. Animate `bullet.locationX` (Sankey) or `bullet.locationY` (Chord) from 0→1 with `loops: Infinity`. Use an adapter on opacity for fade effect. See `references/flow.md` → \"Animated bullets along links\".\n15. **`MapPointSeries` needs `latitudeField`/`longitudeField` when your data fields are named anything other than `latitude`/`longitude`** — Since 5.16.1 the series defaults to `latitudeField: \"latitude\"`, `longitudeField: \"longitude\"`, so data using exactly those names works with no declaration. Any other naming (`lat`/`lng`, `y`/`x`, …) must be declared or the points silently won't appear: `am5map.MapPointSeries.new(root, { latitudeField: \"lat\", longitudeField: \"lng\" })`. Neither is needed with `pushDataItem({ latitude: ..., longitude: ... })`, which passes coordinates directly. On amCharts **older than 5.16.1** there were no defaults, so declare the fields explicitly if you must support those versions.\n16. **`data.setAll()` does NOT animate — use `data.setIndex()` for animated updates** — When the user asks to update/refresh data with animation, do NOT use `series.data.setAll(newData)` — it replaces everything instantly with no transition. Instead, update each item with `series.data.setIndex(i, newItem)` which triggers smooth value animation. For full replacement with animation, loop: `newData.forEach(function(item, i) { series.data.setIndex(i, item); })`.\n17. **`color.lighten()` / `color.darken()` are NOT instance methods** — `am5.color(0xff0000).lighten(0.3)` does NOT work. Use static methods: `am5.Color.lighten(color, 0.3)` to lighten, `am5.Color.lighten(color, -0.3)` to darken. There is NO `darken()` method — use negative lighten. Also available: `am5.Color.brighten()`, `am5.Color.saturate()`.\n18. **Venn diagram has no `VennDiagram` class** — `am5venn.Venn` is pushed directly into a `Container`, NOT into a chart's `series`. See `references/venn.md`.\n19. **Timeline `AxisRendererCurveX` requires `yRenderer`** — Always create the Y renderer first, then pass it: `am5timeline.AxisRendererCurveX.new(root, { yRenderer: yRenderer })`. Without this, crashes with `Cannot read properties of undefined (reading 'axis')`.\n20. **Gantt data uses TWO separate calls** — Do NOT use `chart.data.setAll()`. Set categories on `chart.yAxis.data.setAll([{id, name, parentId, color}])` and tasks on `chart.series.data.setAll([{id, start, duration, progress, linkTo}])`. Use flat `parentId` for hierarchy, NOT nested `children` arrays. CDN order: `index.js` → `xy.js` → `plugins/colorPicker.js` → `gantt.js` → `themes/Animated.js` (gantt.js webpack-depends on colorPicker chunk). See `references/gantt.md`.\n21. **No continent-level geodata at top-level CDN** — `geodata/europeLow.js` does NOT exist. Use `geodata/region/world/europeLow.js` (global: `am5geodata_region_world_europeLow`) or filter `worldLow` with `include: [...]`. On unpkg the same path is under the geodata package's `dist/`: `https://unpkg.com/@amcharts/amcharts5-geodata@<version>/dist/region/world/europeLow.js`.\n22. **Do not add chart titles as HTML** — HTML titles are outside the chart and won't appear in exports. Use `am5.Label` pushed into the container BEFORE the chart, with `verticalLayout` on the container. See \"Chart title\" section above.\n23. **`XYChartScrollbar` has no `xAxis`/`yAxis` settings** — its preview is a chart of its own, `scrollbar.chart`: push the preview's axes into `scrollbar.chart.xAxes`/`yAxes`, its series into `scrollbar.chart.series`, and give that series the data. Axes passed to `XYChartScrollbar.new()` are never added to the preview (its series then throws), and `get(\"xAxis\")` only hands back whatever you passed. See `references/xy.md` → Scrollbar.\n24. **`am5.color()` only accepts hex integers or CSS strings** — `am5.color(0xff0000)`, `am5.color(\"#ff0000\")`, `am5.color(\"rgb(255,0,0)\")` are valid. `am5.color({ r: 255, g: 0, b: 0 })` is NOT — it throws.\n25. **`MapChart` has no default `colors`** — it inherits the `colors` setting from `SerialChart`, but no theme sets it on a map, so `chart.get(\"colors\")` returns `undefined`, and map series don't use it anyway. XY and Radar charts (and percent series, via `series.get(\"colors\")`) get a ColorSet from the theme. For maps, make your own: `am5.ColorSet.new(root, {})`.\n26. **`VoronoiTreemap` has NO `.rectangles` property** — Unlike `Treemap` (which has `series.rectangles.template`), `VoronoiTreemap` renders organic polygon cells. Style via `series.nodes.template` and its children, not `.rectangles`.\n27. **Labels with data placeholders need `populateText: true`** — `Label` defaults to `populateText: false`; labels the library makes for you (axis, legend, tooltip, pie/funnel slice labels, hierarchy and flow node labels…) get `true` from their own theme rules, but a `Label` you create does not. Any Label you create whose `text` has `{placeholders}` (a bullet sprite, a child of a bullet's container, a map point label) needs `populateText: true`, or it shows the braces literally. Example: `am5.Label.new(root, { text: \"{name}\", populateText: true, ... })`. A `tooltipText` is filled in regardless.\n28. **Easing: `am5.ease.in()` does NOT exist** — amCharts 5 provides base easing functions (`am5.ease.cubic`, `am5.ease.bounce`, `am5.ease.elastic`, `am5.ease.linear`, `am5.ease.quad`, `am5.ease.sine`, `am5.ease.circle`, `am5.ease.exp`; `am5.ease.pow(t, e)` takes an exponent, so it is only usable wrapped: `(t) => am5.ease.pow(t, 3)`) and three modifiers: `am5.ease.out()`, `am5.ease.inOut()`, `am5.ease.yoyo()`. Usage: `am5.ease.cubic` (ease-in by default), `am5.ease.out(am5.ease.cubic)` (ease-out), `am5.ease.inOut(am5.ease.cubic)` (ease in+out). There is NO `am5.ease.in()` — using it throws a runtime error. The base functions already ease-in by default.\n29. **`forceHidden` vs `visible`** — `forceHidden: true` ALWAYS hides an element, immune to states, themes/library and even `show()`. `visible` is weaker: amCharts re-manages it on many elements (notably cursor lines, but also labels, ticks, tooltips, grid) in response to interaction or data changes, so a `visible: false` you set may be flipped back to `true`. Rules of thumb: for a **persistent hide**, use `forceHidden: true` (`cursor.lineX.set(\"forceHidden\", true)`, `yRenderer.labels.template.set(\"forceHidden\", true)`, `xRenderer.grid.template.set(\"forceHidden\", true)`). To **reveal** an element that defaults hidden — notably **axis ticks** (`ticks.template` defaults to `visible:false`) — you must raise `visible: true`; flipping `forceHidden` alone won't show it. For cursor lines specifically, always access `cursor.lineX`/`cursor.lineY` after creation — do NOT pass them as constructor options.\n30. **`snapTooltip: true` on series for cursor tooltip snapping** — When using a cursor and you want tooltips to snap to data points, set `snapTooltip: true` on the series in addition to (or instead of) `snapToSeries` on the cursor. This is especially useful for timeline/curve charts.\n31. **Globe rotation uses negative coordinates** — To center the globe (`geoOrthographic`) on a geographic point, set `rotationX` to **-longitude** and `rotationY` to **-latitude**. E.g., to center on Paris (48.86°N, 2.35°E): `chart.animate({ key: \"rotationX\", to: -2.35 }); chart.animate({ key: \"rotationY\", to: -48.86 });`. Using positive values rotates the globe the wrong way.\n32. **`positionOnLine` with multi-segment lines limits per-segment control** — `MapPointSeries` data items can animate along a line via `positionOnLine` (0→1). If the line has 3+ points (multi-segment), position 0.5 is the midpoint of the *entire* path, making per-segment effects (scaling at each segment midpoint, pausing between segments, etc.) difficult. For advanced per-segment animations, use **single-segment lines** (2 points each) and animate the bullet across them sequentially. E.g., instead of one line [A,B,C,D], create [A,B], [B,C], [C,D].\n33. **Do NOT exclude Antarctica (`exclude: [\"AQ\"]`) by default** — Many amCharts demos exclude Antarctica because they use Mercator projection where it appears disproportionately large. This is a demo-specific choice, not a best practice. Unless the user explicitly asks to exclude Antarctica, or references a demo that does so, keep Antarctica in the map. With non-Mercator projections (`geoNaturalEarth1`, `geoEqualEarth`, `geoOrthographic`, `geoEquirectangular`), Antarctica renders at a reasonable size.\n34. **Custom GeoJSON for `MapPolygonSeries` needs CLOCKWISE exterior rings** — amCharts projects on a sphere (d3-geo), where ring winding decides which side is \"inside\". The RFC 7946 default is counter-clockwise, which d3-geo reads as *the whole globe minus the polygon*, so every polygon floods the entire map and the real shape shows only as a sliver. Programmatically generated GeoJSON (grids, cells, buffers) is usually CCW. amCharts does **not** auto-rewind — reverse only the polygons that come out inside out: if `am5map.getGeoArea({ type: \"Polygon\", coordinates: poly }) > 2 * Math.PI`, then `poly.forEach(ring => ring.reverse())`. That is safe on clockwise data and also catches small rings flipped by simplifying or rounding. See `references/map.md`.\n35. **`axis.dispose()` does NOT remove the axis from `chart.xAxes`/`chart.yAxes`** — unlike `series.dispose()`, which self-removes from `chart.series`. A disposed axis stays in the list, keeps showing up in anything built from `chart.yAxes`, and makes `ChartSerializer` throw `Template is disposed`. Remove axes with `chart.yAxes.removeValue(axis)` (or `removeIndex(i)`) — the list auto-disposes the removed axis, no separate `dispose()` needed.\n36. **Declare bullet callbacks as `function(root, series, dataItem)`** — amCharts passes all three; closing over an outer `root` works at runtime but breaks JSON round-trips (`ChartSerializer` captures the function source, and the outer `root` dangles on re-bind). Every `series.bullets.push(...)` in these references uses the parameter form — copy it.\n37. **Several colors in one `am5.Graphics` `draw`** — `endFill()` fills everything since the last `beginPath()`, so start each color with `display.beginPath()`, or the last color paints over all shapes. Don't give such a Graphics its own `fill` either: after `draw` runs it fills the current path once more, so the last shape takes the Graphics' own `fill` (the default theme sets none). E.g. `draw: function (display) { display.beginPath(); display.beginFill(am5.color(0xff0000)); display.drawRect(0, 0, 10, 10); display.endFill(); display.beginPath(); display.beginFill(am5.color(0x0000ff)); display.drawRect(10, 0, 10, 10); display.endFill(); }`. An own `stroke` re-strokes the last path the same way.\n38. **Changing a value on a data item moves nothing** — series draw from the working values: set `valueYWorking` (XY) or `valueWorking` (pie) along with the value, or use `series.data.setIndex()`. See \"Dynamic data\".\n39. **A setting changed after a hover snaps back on unhover** — the `\"default\"` state keeps the value from before the first hover. Change it there too: `sprite.states.lookup(\"default\")?.set(\"fill\", c)`. See \"States\".\n40. **`templateField` goes on the template, not on the series** — per-item settings from data rows are read by the elements a template makes: `series.columns.template.set(\"templateField\", \"columnSettings\")`, likewise `slices.template`, `mapPolygons.template` or a bullet sprite. Set on the series, `templateField` does nothing and every column stays the same. For a pattern per column, see `references/xy.md` → \"Different pattern per column\".\n41. **A JSON-config map that draws nothing with npm imports** — the config names its geodata (`\"geoJSON\": \"am5geodata_worldLow\"`), and with npm imports there is no global of that name. Pass the pack in `resources` (5.21.4): `JsonParser.parse(config, { parent, resources: { am5geodata_worldLow } })`, `element.resources`, or the framework packages' `resources` prop. The same goes for a locale (`am5locales_de_DE`). Since 5.21.4 a console warning names the missing pack. Before 5.21.4, set `window.am5geodata_worldLow = am5geodata_worldLow` after importing it. A config serialized from such a chart copies the whole pack unless `ChartSerializer` gets the same `resources`.\n42. **An `am5.Graphics` redraws only when `draw` changes** — `graphics.set(\"draw\", fn)` with the function it already has does nothing. Pass a new closure that captures the new points: `graphics.set(\"draw\", (display) => paint(display, points))`.\n43. **A legend value without a cursor needs `calculateAggregates`** — `legendValueText` is used only under a cursor; otherwise the value label shows `legendRangeValueText`, which has no data item: `{valueY}` is empty there, and `{valueYClose}` (the latest value), `{valueYSum}`, `{valueYHigh}` and the other range values are empty unless the series has `calculateAggregates: true` (no warning, 5.21.5). See `references/xy.md` → Legend.\n44. **`#,###` does not round** — a number format without a `.` keeps every decimal (`6,708.044000000005` while animating); end it with `.` for whole numbers (`'#,###.'`) or give the decimals (`'#,###.00'`). Every number placeholder also gets a thousands separator, so `{year}` shows `2,024`: use `{year.formatNumber('#')}`. Sections are split by `|`, not `;`. See \"Number formats\".\n\n## Easing functions\n\namCharts 5 easing functions live under `am5.ease`:\n\n```js\n// Base functions (ease-in by default) — these 8 are also the names `animations` / byName() accept:\nam5.ease.linear    am5.ease.quad     am5.ease.cubic\nam5.ease.sine      am5.ease.circle   am5.ease.exp\nam5.ease.bounce    am5.ease.elastic\n\n// pow(t, e) needs an exponent — passing am5.ease.pow directly gives NaN. Wrap it:\n(t) => am5.ease.pow(t, 3)\n\n// Modifiers — wrap a base function:\nam5.ease.out(am5.ease.cubic)      // ease-out\nam5.ease.inOut(am5.ease.cubic)    // ease in + out\nam5.ease.yoyo(am5.ease.cubic)     // animate to end, then back to start\n\n// Usage in .animate():\nsprite.animate({\n  key: \"y\", to: 100, duration: 400,\n  easing: am5.ease.out(am5.ease.cubic)\n});\n\n// Name <-> function (5.20.8)\nam5.ease.byName(\"cubic\", \"out\");                    // same as am5.ease.out(am5.ease.cubic); unknown name -> linear\nam5.ease.easingInfo(am5.ease.yoyo(am5.ease.sine));  // { easing: \"sine\", yoyo: true }\n```\n\n**There is NO `am5.ease.in()`** — the base functions already ease-in by default. `easingInfo()` returns `undefined` for custom functions, `pow`, and combinations it cannot name (e.g. `out(yoyo(x))`) — such easings cannot go into an `animations` entry, and a code-started endless loop using one is not serialized.\n\n## Validate generated code (if you can execute commands)\n\nIf you have the ability to run shell commands, validate your generated chart code before delivering it to the user:\n\n1. Save the complete HTML+JS to a temp `.html` file\n2. Open it in a headless browser (Puppeteer, Playwright, or similar) and collect console errors for a few seconds\n3. If JavaScript errors are found, fix them and re-validate\n\nSkip this step entirely if you cannot execute code (e.g., chat-only context with no tool access).\n\n## Recent API changes\n\nLatest release covered here: **5.22.0** (2026-11-16), with geodata 5.2.0, and the framework packages react 5.0.1, vue 5.0.2, angular 5.0.1, svelte 5.0.3 (2026-10-23) and react-native 5.0.3 (2026-11-16). These are the renames, new settings and behavior changes that code written from older knowledge most often gets wrong — prefer these names/settings. For exact types and defaults, use the typings (`*.d.ts`) or the amCharts MCP server's `get_api_reference`, which is generated from them; for anything newer, verify against the live docs (see next section).\n\n**Renamed settings (old name still works but is deprecated — use the new one):**\n\n| Class(es) | Old | New | Since |\n|-----------|-----|-----|-------|\n| `MovingAverage`, `MovingAverageDeviation`, `MovingAverageEnvelope`, `BollingerBands` | `type` | `maType` | 5.18.0 |\n| `VoronoiTreemap` | `type` | `shapeType` | 5.18.0 |\n\n```js\n// Moving-average indicators: use maType, not type\nam5stock.MovingAverage.new(root, { maType: \"exponential\", period: 20 });\nam5hierarchy.VoronoiTreemap.new(root, { shapeType: \"rectangle\" }); // was: type\n```\n\n**Breaking change — WordCloud internals (5.20.1):** the layout is now computed synchronously in one pass (much faster). The per-data-item `ghostLabel` is gone and labels live in an internal container, so `dataItem.get(\"ghostLabel\")` and any code walking `series.children` to find labels must be updated — use `series.labels` / `dataItem.get(\"label\")` instead.\n\n**Framework packages (5.0.0, 2026-10-22):** `@amcharts/amcharts5-react`, `@amcharts/amcharts5-vue`, `@amcharts/amcharts5-angular`, `@amcharts/amcharts5-svelte` and `@amcharts/amcharts5-react-native`. They make and dispose the chart with the component and work with server rendering. Prefer them over hand-written `Root.new()`/`dispose()` code in those frameworks. See \"Frameworks\".\n\n**New in 5.22.0 (2026-11-16):**\n- **Script files on npm CDNs:** the npm package has the script files in `dist/`, so jsDelivr and unpkg serve them (see \"Plain HTML, no bundler\"). Geodata 5.2.0 has `dist/` too, on unpkg.\n- **Fitting small charts:** `autoLabels` on axis renderers, `PieSeries` and other series; `keepInView` on axis labels; `autoFit` on `Legend`; `autoHide` on chart scrollbars; and the theme `am5themes_ResponsiveMax`, which turns them on (`keepInView` on charts 400 px or smaller). See \"Responsive rules\".\n- **JSON:** a config is read as data, so one from users or another site cannot run script. Parse a config of your own that needs more with `trusted: true`. See `references/json.md`, \"Configs from others\".\n- **Map zooming:** `zoomToGeoBounds()`, `zoomToDataItem()` and click zoom fit what is drawn, also on globes and curved projections.\n  - Bounds with `right` less than `left`, or past ±180, cross the date line. On a flat map the two sides meet only with a rotation passed, e.g. `zoomToGeoBounds(bounds, 500, -180)`.\n  - A `zoomToGeoBounds()`, `zoomToDataItem()` or `zoomToGeoPoint()` call before the map is drawn zooms once it is.\n  - Zooms keep `rotationZ`.\n  - Two `zoomToGeoPoint()` or `zoomToPoint()` calls in a row without animation end in the right place.\n- **Maps, data:**\n  - GeoJSON feature properties are read as data fields: with `valueField: \"value\"` set, a custom GeoJSON with `\"properties\": { \"value\": 12 }` gives each polygon its value without data rows, and heat rules their range. `\"properties\": null` no longer throws.\n  - A series with heat rules whose `geoJSON` is set later (a drill-down) draws.\n  - When `include` and `exclude` both list an item, `exclude` wins.\n  - The `zoomControl` is no longer drawn twice.\n  - A map with panning and `pinchZoom` off no longer blocks page scrolling on touch screens.\n- **Heat rules:** values outside `minValue` / `maxValue` get `min` / `max` instead of going past the ends. On a `logarithmic` rule, zero and below get `min`.\n- **Number formats:** a modifier right after the digits, as in `#,###s`, keeps the thousands separator.\n- **ValueAxis:** a `logarithmic` axis with `min: 0` starts at `treatZeroAs`, or where the data starts, instead of drawing nothing.\n- **Colors and drawing:**\n  - `LinearGradient` takes any `rotation` (5.20.8 to 5.21.5 drew only 0 to 90).\n  - An empty `ColorSet` `colors` list starts from `baseColor` instead of crashing.\n  - A `PicturePattern` the size of its picture shows it.\n  - `drawEllipse(x, y, …)` draws at x, y.\n- **Series and bullets:**\n  - Bullets that take the series color follow it when it changes.\n  - Setting `minBulletDistance` back to 0 shows the bullets again.\n  - `data.setIndex()` and `updateData()` apply the row's `templateField` settings.\n- **Pie labels:** a label hidden with `forceHidden` no longer leaves a gap in its column. `PyramidSeries` and `PictorialStackedSeries` with `alignLabels: false` keep their labels on their slices.\n- **Gantt:** charts with many tasks load several times faster and scroll two to three times as fast. The date rows' labels use `keepInView`, and on a narrow chart a view of two to four weeks shows months in the top row instead of labels on top of each other.\n- **Hierarchy:** after `data.setAll()`, a `VoronoiTreemap` draws again, and a drilled-down Treemap or Sunburst shows the new data from the top.\n- **Word cloud:** a number as a category (a year) no longer throws, but shows formatted, `2,025`. See `references/wordcloud.md`.\n- **Right to left:**\n  - `am5.Root.new(\"chartdiv\", { direction: \"rtl\" })` draws text right to left and lays out legends from the right. See \"Legend\".\n  - Containers take `direction: \"rtl\"`, which lays out a horizontal or grid layout from right to left and lines a vertical layout's children up on the right.\n  - On a `dir=\"rtl\"` page, labels are placed right as well as drawn right to left (each sat off by its own width).\n  - A `Label` with a `width` keeps its text inside its box for every `textAlign` and `direction`.\n- **Text:** font names with spaces, and font lists such as `[fontFamily: 'Source Code Pro', monospace]`, are read right. Center- or right-aligned wrapped text no longer draws its bold or colored parts out of place.\n- **TypeScript:** `am5.IGraphics` and `am5.Animation` work as types.\n- **Size:** the script builds are smaller (`index.js` by about 50 KB, 10 KB gzipped), and they no longer define the global `regeneratorRuntime`. The npm package installs only the d3 modules it uses, not the whole `d3`.\n- **Geodata 5.2.0:** Nauru is named \"Naoero\" (on the CDN since 5.20.2); its id `NR` is unchanged.\n- react-native 5.0.3 loads 5.22.0, so its `themes` take `\"ResponsiveMax\"` too.\n\n**New in 5.21.5 (2026-10-26):**\n- `am5.renderToSVG()` writes SVG that design tools such as Figma read correctly, and its new option `includeNonExportable` also writes elements marked `exportable: false`. See \"SVG export\".\n- JSON: theme colors in data (e.g. a column's `fill` from a `templateField`), and colors a color set makes after its theme's list runs out, are saved as references (`\"@colors.getIndex(n)\"`, `\"@root.interfaceColors.get(...)\"`), so they follow the theme the config is parsed with.\n- Fixed: color sets of one chart that made more colors than their theme's list could repeat colors another set had already made. With `am5themes_Adaptive`, JSON saved the palette's first color as the primary button color.\n- npm: a bare `import \"@amcharts/amcharts5/element\"` defines `<am5-chart>` with esbuild too. `defineChartElement()` still works.\n- react-native 5.0.2 loads 5.21.5.\n\n**New in 5.21.4 (2026-10-23):**\n- `resources` gives a JSON config the geodata and locales it names (`\"geoJSON\": \"am5geodata_worldLow\"`, `\"locale\": \"am5locales_de_DE\"`) when they aren't globals, as with npm imports. It's taken by:\n  - `JsonParser.parse(config, { parent, resources: { am5geodata_worldLow } })`;\n  - `ChartSerializer.new(root, { resources })`, which then writes those packs by name instead of copying them whole;\n  - `<am5-chart>` (`element.resources`);\n  - the framework packages' `resources` prop.\n\n  A name that can't be found now logs a warning. Before, the map was just blank. See \"Serializing to JSON\" and `references/json.md`.\n- `<am5-chart>` and the framework packages take a theme with its settings: `[am5themes_Adaptive, { baseColor: \"#4150a0\" }]`. The `themes` attribute takes the same as JSON: `themes='[\"Animated\", [\"Adaptive\", { \"baseColor\": \"#4150a0\" }]]'`.\n- The framework packages' new versions (react 5.0.1, vue 5.0.2, angular 5.0.1, svelte 5.0.3, react-native 5.0.1) have both, and the web ones need amCharts 5.21.4 or later.\n\n**New in 5.21.3 (2026-10-21):**\n- `ColorSet` `repeatLightness`: themes that reuse their colors (Adaptive, Monochrome, Kelly, Material, Nord, Pastel and others, but not Colorblind or Patterns) now make each repeat of the list 10% lighter. For the old behavior, set `repeatLightness: 0` through a theme rule, `rule(\"ColorSet\").set(\"repeatLightness\", 0)`: the color sets of a root share one list. In the Adaptive and Monochrome theme settings, use `false`. See \"ColorSet\".\n- JSON: palette colors are written as `\"@colors.getIndex(n)\"`, so they follow the theme the config is parsed with. A `step` or `passOptions` set on a chart's colors round-trips without the theme's palette. Data-item loops that differ per item are saved per item. See \"Serializing to JSON\".\n- Maps: d3 projections with a shape of their own (HEALPix, Armadillo, Berghaus, interrupted and polyhedral) display properly, and switching projections at zoom level 1 shows the whole map again.\n\n**New in 5.21.2 (2026-10-14):**\n- Interface color `warning`: a yellow between `negative` and `positive` (default `#f2c230`; themes with their own `positive`/`negative` have a matching one), for the middle of a bad-to-good scale: `root.interfaceColors.get(\"warning\")`.\n- `am5.Color.interpolateColors(position, colors, mode?)`: a color on a scale through any number of colors, evenly spaced (`position` 0–1, clamped; `mode` `\"rgb\"` (default) or `\"hsl\"`). Through `[negative, warning, positive]` it avoids the brown middle of `Color.interpolate(t, negative, positive)`. See \"Colors\".\n- Heat rules: `stops` (numbers, percents or colors, all of one kind) in place of `min`/`max`, for a scale through more than two values. `HeatLegend`: `colors` in place of `startColor`/`endColor`, a gradient through them with `stepCount: 1` or one step per color otherwise (`stepCount` is then ignored). See \"Heat rules\".\n- `am5themes_Adaptive` and `am5themes_Monochrome`: `interleave`, `mapShade` and `keepContrast` (all off by default). See \"Parameterized themes\".\n- Fixed: a ColorSet `step` with a theme that reuses its colors used only two or three of them (word clouds and treemaps with Nord, Pastel or Adaptive), see \"ColorSet\"; `RadialGradient` with pixel `x`/`y` was off-center on radar fills and similar shapes in 5.21.1.\n\n**Behavior changes / fixes (5.21.1, 2026-10-13)** — no workaround needed any more:\n- `root.timezone`: charts were up to 16 times slower with it, and grid, labels, data groups and date math could be an hour off around a daylight saving change. A `DateAxis` grid of several hours now stays on the clock after a DST change (where the clocks skip a grid time, the line goes at the jump). `PeriodSelector` and `DateRangeSelector` follow `root.timezone`/`root.utc` (they used the viewer's time zone). Date formats `Z`, `ZZ`, `x`, `i`, `I` are right with `root.timezone`, and `YYYY`, `ww`, `W`, `DDD` honor `root.utc`.\n- `DataProcessor`: string dates in `dateFields` without a `dateFormat` were all read as 1 January 1970. Now the browser's `Date` parses them, and a date-only `\"2024-03-15\"` is midnight UTC. See \"Data processor\".\n- A chart in a container scaled with CSS (`transform` or `zoom`) was scaled twice, and clicks hit the wrong elements.\n- Maps: a `zoomLevel` set before the map loaded was ignored or left the map blank; `MapSankeySeries` bands follow `linkColorMode` and node fill changes, and nodes without coordinates are drawn; raised map lines (`MapLine` `altitude`) draw 3–4 times faster.\n- `RadialGradient` is centered on map polygons, line and area fills and bullets (with `target` set, on the target). `Picture`: changing a shadow setting after the image loaded no longer removes the image. `CurveChart`: a path scaled down to fit no longer gets far too many labels and grid lines. Responsive theme: XY axis ticks on small charts are no longer moved inside the plot.\n\n**New in 5.21.0 (2026-10-08):**\n\n*Rendering, export, chart element*\n- SVG rendering: `renderer: am5.SVGRenderer` in `Root.new()` settings (only when the root is created), or `am5.Root.defaultRenderer = am5.SVGRenderer` before creating roots. Canvas stays the default; charts look and behave the same; blend modes `DST_OVER`, `SRC_ATOP` and `XOR` are canvas-only. See \"Root element setup\".\n- `am5.renderToSVG(rootOrElement, options?)` — SVG markup of the chart (or of one element, e.g. `pixelSeries.pixels`) as last drawn, from either renderer; screen readers read it as one image named by `title` / the Root `ariaLabel`. Exporting plugin: `\"svg\"` format (`download(\"svg\")`, `getSVG()`, `exportSVG()`, `svgOptions`), listed in `ExportingMenu` by default. See \"Exporting\".\n- `<am5-chart>` element — a chart from a JSON config (`config` or `src`), with `themes` and `renderer=\"svg\"`; load `element.js` after `plugins/json.js`, or with npm import `defineChartElement` from `@amcharts/amcharts5/element` and call it. See \"Serializing to JSON\".\n- The npm package now ships `AGENTS.md`, `docs/` (a bundled copy of these notes, possibly older) and `examples/<name>/index.ts` (62 also as `config.json`; `examples/examples.json` lists what each shows) — when the package is installed, those examples are verified starting points.\n\n*Maps* (details and snippets in `references/map.md`)\n- `am5map.MapRasterSeries` — a whole-world equirectangular image (e.g. `https://cdn.amcharts.com/lib/5/geodata/images/earthDay2048.jpg`) reprojected as the map turns and zooms (WebGL2 where it can); `nightSrc` + `sunDate`/`sunPosition` show day and night.\n- `am5map.NightSeries` — shades the night side in twilight steps and shows the sun: `sunDate` (`\"now\"`, timestamp, date string or `Date`) or `sunPosition`; `sunAltitude` (metres) keeps the sun in view past a globe's edge. `am5map.getSunPosition(date?)` returns the `{ longitude, latitude }` where the sun is overhead.\n- `am5map.PixelMapSeries` — polygons drawn as a grid of pixels (`pixelType`, `step`, `uniform`, `columnHeight` with `MapPolygon` `pixelHeight`, or the series' `pixelHeightFunction`); heat rules, states and tooltips work as on `MapPolygonSeries`.\n- `MapLine` `altitude` (metres; each leg arcs) and `MapPointSeries` `altitudeField` (no default) raise lines and points; `MapPointSeries` `surfaceBullets` lays bullets on the map surface; `MapChart` `autoHome` goes home once loaded; `MapPolygonSeries` `clickZoom` zooms to a clicked polygon and back.\n\n*Core*\n- `autoAppear` / `appearDuration` / `appearDelay` on every element — `appear()` as settings, so JSON configs get the opening animation. See \"Animations\".\n- `Root` `forcedColors` (default `true`) — interface colors follow Windows High Contrast. See \"Accessibility\".\n- `Scrollbar` `outsideAxes` — `true` puts a chart's scrollbar beyond the axes on its side, `false` between them and the plot; unset, the chart decides. Only for `scrollbarX`/`scrollbarY`. See `references/ui-elements.md`.\n- `ChartSerializer`/`JsonParser`: colors from `root.interfaceColors` are saved as `\"@root.interfaceColors.get('…')\"` references (they follow the theme the config is parsed with); data-item loops, hidden series, elements added to plot/axis containers, `Date` values and more are now saved. See \"Serializing to JSON\".\n- Accessibility: `ariaExpanded` setting, `Modal` `ariaLabel`, keyboard changes (ESC, SPACE, arrows in draggable groups). See \"Accessibility\".\n- New locale prompts, translated in all locales: \"OK\", \"Cancel\", \"Delete\", \"Settings\", \"Expand\", \"Move Up\", \"Move Down\".\n\n**Behavior changes (5.21.0)** — existing code may now render or act differently:\n- A hidden element (`visible: false`, `forceHidden` or `hide()`) no longer takes up space in a container sized to its content — e.g. a hidden XY scrollbar no longer leaves an empty band above the plot.\n- `DataProcessor` `emptyAs` replaces only `null`, `undefined` and `\"\"` — no longer `0` and `false`.\n- `Label` `fillOpacity: 0` now hides the text (it was ignored). `strokeWidth: 0` now draws no line (was 1 px) and `shadowOpacity: 0` no shadow (was a full one).\n- Heat rules: `minValue: 0` / `maxValue: 0` are honored (the data's lowest/highest value was used instead).\n- Bullets with `stacked: \"up\"` (or `\"auto\"` in the lower half) on a vertical series stack instead of overlapping.\n- `calculateAggregates` on non-XY series (pie, map heat maps): `valueChange`, `valueChangePercent` and the like are numbers now (were `NaN`), and right on bubble series.\n- `Gantt`: the category axis' `colorField` and `nameField` are honored (bar colors were always read from `color`).\n- `Sunburst` ignores `singleBranchOnly` (always `true`). `StockToolbar` `focusable` now defaults to `true`.\n- Responsive theme: minor axis labels are hidden only on charts 600 px or smaller (was 1000 px), so turned-on minor labels show on mid-size charts.\n- `PatternSet` starts over from its first pattern past the end of its list (elements after the 17th got no pattern).\n- `DurationFormatter`: codes `H`, `D`, `Y`, `K`, `k`, `n` work (as `h`, `d`, `y`, `h`, `h`, `S` — e.g. `\"HH:mm:ss\"` gave `NaN`); durations between a month and a year use the month formats again (`1m 15d 00:00:00`, not `45d 00:00:00`), which `DurationAxis` labels show.\n- `am5.CSVParser` honors `skipEmpty: false` (empty lines were always skipped). `series.updateData([])` removes every data item (it kept the first).\n- A `fontSize` given as a number in a string (`\"8\"`) counts as pixels (was ignored). Filters (`brightness`, `saturate`, `blur`, …) combine instead of replacing each other, and one set back to neutral turns off.\n- A logarithmic `ValueAxis` with values ≤ 0 logs a console warning pointing to `treatZeroAs` (it silently drew nothing).\n- `am5.Color.alternative(color)` without light/dark colors returns black for light colors (it always returned white). Date format `YYYY` is right west of UTC. `Label` `maxChars` cut at a word boundary uses the `ellipsis` setting.\n- Exporting: CSV/HTML with `pivot: true` follow `dataFieldsOrder` (were reversed); HTML `headerClass` is applied; `maxHeight` shrinks the image.\n- Fixes that remove old workarounds (details in the references): map `goHome()` before the map is ready or on a globe, `zoomToGeoBounds()` duration and bounds, dragging a zoomed map to its edges, `lineType` changes; `innerRadius: am5.percent(0)` on pie/radar/gauge; `AxisRendererRadial` negative `radius`; `SmoothedRadarLineSeries` `tension`, `ForceDirected` forces, `Partition`/`Sunburst` `nodePadding`, `Sunburst` angles and `Chord` `sort: \"none\"` changed after drawing; `WordCloud` word filtering (`minValue` / `minWordLength` / `excludeWords`); stock indicator column colors; `GaplessDateAxis` with grouped data and `root.timezone`.\n\n**Behavior changes / fixes (5.20.6 – 5.20.8)** — no workaround needed any more:\n- `CategoryAxis` (5.20.6): series data no longer has to follow the axis-category order for every item to be drawn (e.g. Gantt-like column charts sorted by date). Line series still connect points in data order.\n- Logarithmic `ValueAxis` over a wide range labels its grid with round powers of ten (5.20.6).\n- Content added to an `axisHeader` after the chart is built (e.g. a legend) now makes the axis leave room instead of covering it (5.20.7).\n- A `Container`'s `background` with its own `templateField` now reads the container's data item (5.20.7), so a per-bullet label background works: `am5.Label.new(root, { text: \"{valueY}\", populateText: true, background: am5.RoundedRectangle.new(root, { templateField: \"labelBg\" }) })` with `labelBg: { fill: am5.color(0xff0000) }` in the data row.\n- `am5.CSVParser.parse(\"\")` no longer loops until \"Invalid array length\" (5.20.7) — an empty server response is safe. It returns `[]` with `useColumnNames: true`, but `[{}]` (one empty row) with default options, so check for that before `data.setAll()`.\n- JSON: `JsonParser` resolves references that point further down the config, and user `themeTags` are serialized — see *JSON config / serialization* below.\n\n**New settings / methods worth knowing:**\n\n*Declared animations, links, map points on lines (5.20.6 – 5.20.8)*\n- `animations` setting on **every** element (5.20.8): an array of `IDeclaredAnimation` entries `{ key, from?, to, duration, delay?, loops?, yoyo?, easing?, ease?, target? }` — animations described as data (`loops: 0` = forever, `easing` by **name**, `target: \"dataItem\"` for data-item values). Round-trips through JSON. `IDeclaredAnimation` is not exported from the package index. See \"Animations\" above for the snippet, defaults and the `from` caveat.\n- `am5.ease.byName(name, mode?)` / `am5.ease.easingInfo(fn)` (5.20.8) — easing function ↔ name; only the 8 named base easings (and `out`/`inOut`/`yoyo` of them) have names. See \"Easing functions\" above.\n- `ChartSerializer`: `runningAnimations` (5.20.8, default `true`) — saves endless code-started loops as `animations` entries. See \"Serializing to JSON\" above.\n- `Series` links (5.20.7): `urlField` (no default — links are off until set) names the data field holding a URL; the data item's `url` field gets it. Clicking the item's bullet (any series), column (`ColumnSeries`, candlestick, OHLC, Gantt…), slice (pie, funnel, pyramid, pictorial, Venn), `MapPolygon` or `MapLine` opens it in `linkTarget` (default `\"_self\"`; `\"_blank\"` opens with `noopener`; a chart inside an iframe usually wants `\"_blank\"` or `\"_top\"`). `cursorOverStyle: \"pointer\"` is set automatically unless you set one. `javascript:`/`data:`/`vbscript:` URLs are never opened. Override `series.openUrl(dataItem)` to intercept clicks. `urlField` can be set after the data, and a URL added later (`data.setIndex()`) links too. **Not linked:** hierarchy nodes, flow nodes/links, word-cloud labels, `MapSankeySeries` nodes.\n- `MapPointSeries` (5.20.6): `lineIdField` (default `\"lineId\"`), `positionOnLineField` (`\"positionOnLine\"`), `autoRotateField` (`\"autoRotate\"`), `autoRotateAngleField` (`\"autoRotateAngle\"`) — a point on a line can be a plain data row `{ lineId: \"jfk-lhr\", positionOnLine: 0.5, autoRotate: true }` instead of `pushDataItem({ lineDataItem, positionOnLine })`, so it is saved by `ChartSerializer`. Data values of `autoRotate`/`autoRotateAngle` win over the bullet's. See `references/map.md`.\n- `MapPointSeries` (5.20.8): an auto-rotating point turns round to face its travel direction on the way back — **only** while a bullet-sprite `animations` entry (`target: \"dataItem\"`, `key: \"positionOnLine\"`, e.g. with `yoyo: true`) moves it toward the line start. A point moved by `dataItem.animate()` in code is not flipped; that code must turn it.\n\n*Themes & styling*\n- 20+ new themes (5.20.0): `Midnight`, `Ember`, `Nord`, `Pastel`, `Colorblind`, `Patterns`, `Petroleum`, `Savanna`, plus `*Dark` variants of most palettes. Two parameterized factory themes, `Monochrome` and `Adaptive` — see \"Parameterized themes\" above.\n- New fill patterns (5.20.0): `am5.StarPattern` (`radius`, `innerRadius`, `spikes`, `gap`, `checkered`) and `am5.TrianglePattern` (`maxWidth`, `maxHeight`, `gap`, `checkered`).\n- `rotateShapes` (5.20.0) on `RectanglePattern`/`StarPattern`/`TrianglePattern`: `rotation` then spins each shape around its own center instead of the whole grid — tiles seamlessly and is much faster. Prefer it over a whole-pattern `rotation` on large tiles.\n- `Series`: `fillGradient` / `strokeGradient` settings, handed to bullets (the series' own fills, lines and columns don't use them: set gradients on `fills.template` / `columns.template` / `strokes.template`). A bullet `Graphics` with no paint of its own (`fill`, `fillGradient`, `fillPattern`, `stroke`, `strokeGradient`) now inherits all of them from its series — and on pie, funnel, flow and hierarchy charts, from its own slice/node (5.20.0–5.20.1).\n\n*XY charts*\n- `XYChart`: `strokeWidths` (array of pixel widths) and `strokeDasharrays` (array of dash arrays) — cycled across line series as they are added, exactly like `colors`. Lets series be told apart without relying on color, e.g. with the `Patterns` theme.\n- `XYCursor`: `clickTolerance` (default `0`) — how many pixels outside the plot area a press may start and still begin a zoom/selection. The selection itself still starts at the plot edge.\n- `XYSeries`: a value field (`valueYField`, `openValueYField`, …) can now be changed after creation — re-set the series data afterwards for it to take effect. A series can also be reassigned to a different `xAxis`/`yAxis` after creation.\n- Column series (`ColumnSeries`, `CandlestickSeries`, `OHLCSeries`, …) (5.20.4): `colorByDataItem: true` (default `false`) gives each column its own color from the series' new `colors` (`ColorSet`) setting — the series makes its own `ColorSet` if none is given. The color lands on the data item's `fill` field. Prefer this over the old \"adapter on `columns.template` `fill`\" recipe: it is declarative and survives JSON serialization.\n- `Scrollbar` (5.20.2): `opposite: true` (default `false`) puts a chart's `scrollbarX` **below** the plot and `scrollbarY` to the **left**, instead of above / right. Only affects scrollbars set via `chart.set(\"scrollbarX\"/\"scrollbarY\", …)`. This is a **different** setting from the long-standing `opposite` on `AxisRendererX`/`AxisRendererY`.\n\n*WordCloud (5.20.1)*\n- `svgPath` arranges words into a shape (experimental), with `maskByShape` to clip them to the outline and `shapeTolerance` to control spill (negative = padding inside). See `references/wordcloud.md`.\n- `randomizeAngles: false` cycles `angles` in order for a reproducible layout; `allowNesting: false` packs words as non-overlapping bounding boxes (use it when labels have opaque backgrounds).\n- `angles` now accepts **any** angle (e.g. `[0, -30, -45]`). Before 5.20.1 only `0`/`±90` were handled, and the old docs said so explicitly — that restriction is gone.\n\n*Core / events*\n- New `globalpointerdown` event on all elements — fires on a press anywhere on the chart surface, mirroring `globalpointermove`/`globalpointerup`.\n- `Root`: `sanitizeHTML` (5.19.0, default `true`) — dynamically-set HTML (`html`/`labelHTML`, HTML tooltips, modal content) is sanitized; set `false` in code to opt out. Since 5.22.0 a JSON config's `root` section can't turn it off unless parsed with `trusted: true`. Exports gained `escapeFormulas` (default `true`) to guard CSV/XLSX against formula injection.\n- `Root`: `ariaLabel` is now applied to the `<div>` holding the chart's focusable elements (5.20.0).\n- `Label`: `oversizedBehavior: \"truncate\"` now ignores `maxHeight` (there is no way to truncate text vertically).\n- A `Container`'s `Rectangle`/`RoundedRectangle` background now defaults `crisp` to `true` unless set explicitly (5.20.0).\n- `Root` (5.20.2): `fontFamily`, `fontSize` (number or string) and `fontWeight` (`\"normal\" | \"bold\" | \"bolder\" | \"lighter\"`, or `\"100\"` … `\"900\"`) settings — defaults for **all** text elements unless overridden on an element. Set them in `am5.Root.new(\"chartdiv\", { fontFamily: \"Inter\" })` or `root.setAll({...})` instead of a custom theme rule on `Label`.\n- `am5.SerialChartContainer` (5.20.2) — a directly usable `SerialChart` whose `seriesContainer` sits inside a `ZoomableContainer` (exposed as `chart.zoomableContainer`), so series such as `ForceDirected` can be zoomed and panned. Exported from the **`am5` root module**, not a chart package. Optional `zoomTools` setting takes a `ZoomTools` instance whose `target` is pointed at the series container automatically. Bullets added to its series are drawn (5.20.4) and flow-chart bullets are placed correctly inside it (5.20.5). See `references/hierarchy.md`.\n\n*JSON config / serialization (5.20.2 – 5.20.8)*\n- `ChartSerializer` now emits **only user-set settings** (5.20.3) — theme and library defaults are left out. Anything diffing or post-processing serializer output must expect much smaller configs.\n- A JSON config may carry a top-level **`root`** section (5.20.2) that applies settings and properties to the `Root` object before the chart is parsed; `ChartSerializer` writes it when `includeRoot: true` (default `false`). A `Root`'s `interfaceColors`, `utc`, `fps`, formatters and `tabindex` round-trip through it (5.20.3). Since 5.22.0 a parsed `root` section sets only those properties, a named locale and Root settings, and sets `sanitizeHTML: false` only with `trusted: true`.\n- `JsonParser.parse(config, { updateTargets: \"soft\" })` (5.20.3) — an option on the **second argument of `parse()`**, not a parser setting. `\"soft\"` applies settings onto an existing object of the same `type` instead of replacing it; default `\"strict\"` replaces. `parse()` is async and returns a Promise.\n- Gantt charts are now serializable/parsable (5.20.3). Cross-references are written as references (`\"@series.get('fill')\"`) instead of copies; large values (a map's `geoJSON`, a `Root`'s locale) are written as the name of the pack they came from and rebuilt on parse.\n- An adapter whose callback did not survive the JSON round-trip is now **skipped** on parse instead of breaking the chart (5.20.4) — adapters still do not round-trip, see \"Serializing to JSON\" above.\n- `ChartSerializer` writes user **`themeTags`** (5.20.6) — only tags passed to `.new()`; tags set later with `set(\"themeTags\", …)` and tags the library adds are left out. On parse the tags are merged into an existing element's.\n- `JsonParser` resolves **forward references** (5.20.7): a setting/property naming a ref defined further down the config is resolved after the rest instead of throwing \"Could not find ref\" — a legend inside an `axisHeader` naming a series now round-trips. Axis-range `axis`/`series` lookups are still immediate, so keep those ordered.\n- Map data rows (5.20.7) no longer carry the geodata's own feature properties (`name`, `CNTRY`, `TYPE`); a row left with only its id is dropped.\n- `animations` round-trip, and an endless code-started loop (`loops: Infinity`, nameable easing) is written as an `animations` entry with its key removed from the settings (5.20.8, `runningAnimations`, default `true`). A loop started on a data item in code is **not** saved in 5.20.8 (it is since 5.21.0).\n\n*Bullets on non-XY charts (5.20.2)*\n- `ArcDiagram`: bullets on nodes are now placed on the node circle, `locationX`/`locationY` being fractions of it (before 5.20.2 they were created but never positioned). Flow charts (`Sankey`/`Chord`): node bullets are children of the node, drawn above its shape and below its label, positioned relative to the node. `FunnelSeries`/`PyramidSeries`: bullet `locationX`/`locationY` follow the slice's sloping edges instead of its bounding box.\n- A bullet `Graphics` with no paint of its own takes the color of **its own slice or node** on pie, funnel, flow and hierarchy charts — so it is the same color as what it sits on and **invisible** unless offset, stroked, or given a contrasting `fill` deliberately. Setting `fill` on the bullet sprite turns the inheritance off.\n\n*Maps*\n- `MapChart` (5.20.2): `doubleClickZoom` (default **`true`** — a behavior change: a double click/tap zooms in, shift + double click zooms out; set `false` to opt out). On maps panned by rotating (`panX: \"rotateX\"` / `panY: \"rotateY\"`) the clicked point rotates to the center, otherwise it stays under the pointer. `boxZoom: \"none\" | \"drag\" | \"shift\" | \"ctrl\" | \"alt\"` (default `\"none\"`) is **not a boolean** — it names the key held while dragging a rectangle to zoom into; `\"drag\"` needs no key, so pair it with `panX`/`panY: \"none\"`. The rectangle is the readonly `chart.boxZoomSelection` element (a `Rectangle`). There are no keyboard-navigation settings on `MapChart`.\n- `MapLineSeries` (5.20.3): `pointIds` data field (`{ pointIds: [\"JFK\", \"LAX\"] }`) names the `MapPointSeries` points a line connects, looked up in the series given by the new `pointSeries` setting; `pointIdsField` (default `\"pointIds\"`) renames the field. `pointsToConnect` wins if both are set. See `references/map.md`.\n- `MapChart`: `projectionName` (5.19.0) — string alternative to `projection`, e.g. `\"geoOrthographic\"`, mainly for JSON config. Register extra ones with `am5map.registerProjection()`. Bundled projections are no longer eagerly imported, so unused ones tree-shake away.\n- `MapSankeySeries` (5.17.0) — Sankey overlaid on a map; auto-resolves `sourceId`/`targetId` once `polygonSeries` geoJSON loads (5.17.1), so no `datavalidated` wrapper needed. See `references/map.md`.\n- `MapPointSeries` defaults changed to `longitudeField: \"longitude\"`, `latitudeField: \"latitude\"` (5.16.1).\n\n*Hierarchy & axes*\n- `Tree`: `fitNodes` (5.18.0, exclude hidden nodes from layout), `nodeSeparation` (5.16.2, custom node-spacing fn), `clustered` (5.16.2, dendrogram layout — leaves at same depth).\n- `ValueAxis`: `syncZeros` (5.16.2, align zero across synced axes — needs `syncWithAxis`).\n- `Hierarchy`: `parentIdField` setting + `setFlatData(data)` method (5.16.2) — feed flat `{id, parentId}` data instead of nested `children`.\n\n*Stock*\n- Indicator numeric settings now enforce min/max limits, so extreme values can no longer freeze the page. `IIndicatorEditableSetting` gained `scale`, `maxValue` and `step` (5.20.0).\n- Volume Profile now spreads each bar's volume across its full high/low range instead of placing it all at the close. Several indicator math fixes (Williams %R, Momentum, RSI, Moving Average Cross defaults, Commodity Channel Index) landed in 5.19.0–5.20.0 — see `references/stock.md`.\n\n*All entities*\n- `onDebounced(key, cb, delay)` / `offDebounced(key, cb?)` and `onPrivateDebounced` / `offDebouncedPrivate` (5.17.3) — fire once after rapid changes settle.\n- `once(key, cb)` and `onceDebounced(key, cb, delay)` (5.20.4) — like `on()`/`onDebounced()` for a **settings** key, but the callback fires only the first time that setting changes, then removes itself. Both return an `IDisposer`. (Distinct from `events.once(\"eventName\", …)`, which has existed for events all along.)\n- `Label`: `fontFamily: \"inherit\"` (5.17.3) uses the chart container's computed font.\n\n## Verify unfamiliar API before using it\n\nIf you are unsure whether a method, property, or setting exists on an amCharts 5 class, **verify it before using it**. Check the class reference (class name in lowercase, e.g. `LineSeries` → `lineseries`):\n\n1. **Primary:** `https://docs.amcharts.com/v5/reference/{classname}/` — e.g. `https://docs.amcharts.com/v5/reference/lineseries/`\n2. **Fallback (if primary is unavailable):** Check the TypeScript source on GitHub — `https://raw.githubusercontent.com/amcharts/amcharts5/master/src/.internal/charts/` and navigate to the relevant file. Settings interfaces are named `I{ClassName}Settings`.\n\nCommon source file paths:\n- XY series: `charts/xy/series/{ClassName}.ts`\n- XY axes: `charts/xy/axes/{ClassName}.ts`\n- Pie: `charts/percent/pie/{ClassName}.ts`\n- Radar: `charts/radar/{ClassName}.ts`\n- Map: `charts/map/{ClassName}.ts`\n- Hierarchy: `charts/hierarchy/{ClassName}.ts`\n- Flow: `charts/flow/{ClassName}.ts`\n- Core sprites: `core/render/{ClassName}.ts`\n"
}

SHA-256 of public snapshot: a579d136f4af25ae984fcc5574d4f6e1da8809bce3e747c83c9679adea78f786