@amcharts/amcharts5-mcp 1.8.0 → 1.9.0

package/extended/getting-started/integrations/react.md

@@ -1,241 +1,185 @@
 ---
 title: "Using amCharts 5 with React"
 source: "https://www.amcharts.com/docs/v5/getting-started/integrations/react/"
-scraped: "2026-03-15"
+scraped: "2026-10-22"
 ---
 
-This tutorial will show you every step you need to use amCharts 5 with React + Vite.
+Use amCharts 5 in React with our [`@amcharts/amcharts5-react`](https://www.npmjs.com/package/@amcharts/amcharts5-react) package. It creates and disposes the chart with your component, and works with server rendering.
 
-## Creating a project
+## Installation
 
-npm create vite@latest my-project -- --template react
-cd my-project
-npm install
-npm install @amcharts/amcharts5
+```shell
+npm install @amcharts/amcharts5 @amcharts/amcharts5-react
+```
 
-Create a new `src/Chart.jsx` file:
+It needs React 18 or later and amCharts 5.21.0 or later.
 
-import { useLayoutEffect } from 'react';
-import \* as am5 from "@amcharts/amcharts5";
-import \* as am5xy from "@amcharts/amcharts5/xy";
-import am5themes\_Animated from "@amcharts/amcharts5/themes/Animated";
+## A chart written in code
 
-function Chart(props) {
-  useLayoutEffect(() => {
-    let root = am5.Root.new("chartdiv");
+`useAmChart()` gives your function a new root. Build the chart in it as in any amCharts example, and put the returned `ref` on an element with a height:
+
+```typescript
+import { useAmChart } from "@amcharts/amcharts5-react";
+import * as am5 from "@amcharts/amcharts5";
+import * as am5xy from "@amcharts/amcharts5/xy";
+import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";
 
-    root.setThemes(\[
-      am5themes\_Animated.new(root)
-    \]);
+function Chart({ data }) {
+  const { ref } = useAmChart((root) => {
+    root.setThemes([am5themes_Animated.new(root)]);
 
-    let chart = root.container.children.push(
+    const chart = root.container.children.push(
       am5xy.XYChart.new(root, {
         panY: false,
         layout: root.verticalLayout
       })
     );
 
-    // Define data
-    let data = \[{
-      category: "Research",
-      value1: 1000,
-      value2: 588
-    }, {
-      category: "Marketing",
-      value1: 1200,
-      value2: 1800
-    }, {
-      category: "Sales",
-      value1: 850,
-      value2: 1230
-    }\];
-
-    // Create Y-axis
-    let yAxis = chart.yAxes.push(
+    const yAxis = chart.yAxes.push(
       am5xy.ValueAxis.new(root, {
         renderer: am5xy.AxisRendererY.new(root, {})
       })
     );
 
-    // Create X-Axis
-    let xAxis = chart.xAxes.push(
+    const xAxis = chart.xAxes.push(
       am5xy.CategoryAxis.new(root, {
-    renderer: am5xy.AxisRendererX.new(root, {}),
+        renderer: am5xy.AxisRendererX.new(root, {}),
         categoryField: "category"
       })
     );
     xAxis.data.setAll(data);
 
-    // Create series
-    let series1 = chart.series.push(
+    const series = chart.series.push(
       am5xy.ColumnSeries.new(root, {
-        name: "Series",
+        name: "Value",
         xAxis: xAxis,
         yAxis: yAxis,
-        valueYField: "value1",
+        valueYField: "value",
         categoryXField: "category"
       })
     );
-    series1.data.setAll(data);
+    series.data.setAll(data);
 
-    let series2 = chart.series.push(
-      am5xy.ColumnSeries.new(root, {
-        name: "Series",
-        xAxis: xAxis,
-        yAxis: yAxis,
-        valueYField: "value2",
-        categoryXField: "category"
-      })
-    );
-    series2.data.setAll(data);
-
-    // Add legend
-    let legend = chart.children.push(am5.Legend.new(root, {}));
+    const legend = chart.children.push(am5.Legend.new(root, {}));
     legend.data.setAll(chart.series.values);
 
-    // Add cursor
     chart.set("cursor", am5xy.XYCursor.new(root, {}));
+  }, [data]);
 
-    return () => {
-      root.dispose();
-    };
-  }, \[\]);
-
-  return (
-    <div id="chartdiv" style={{ width: "500px", height: "500px" }}></div>
-  );
+  return <div ref={ref} style={{ width: "100%", height: "500px" }}></div>;
 }
+
 export default Chart;
+```
+
+-   The chart is made again when a value in the second argument (`[data]` here) changes. Leave it out to make the chart once.
+-   The chart is disposed when the component goes away. The double mount of React's strict mode is handled.
+-   The element can be rendered later, e.g. after a loading message: the chart is made when it is there.
+-   `useAmChart(setup, deps, { renderer: "svg" })` draws the chart as SVG.
+-   If your function throws, the error goes to the nearest error boundary.
 
-You can now import and use the `Chart` component inside of `src/App.jsx`:
+### Updating without making the chart again
 
-import { useState } from 'react'
-import reactLogo from './assets/react.svg'
-import viteLogo from '/vite.svg'
-import Chart from './Chart';
-import './App.css';
+`useAmChart()` also returns `root`, and `result`: what your function returned. Keep what you need there and change it when the data changes:
 
-function App() {
-  return (
-    <>
-      <Chart />
-    </>
-  )
+```typescript
+import { useEffect } from "react";
+import { useAmChart } from "@amcharts/amcharts5-react";
+
+function Chart({ data }) {
+  const { ref, result } = useAmChart((root) => {
+    // ... the chart, as above, without setting data
+    return { xAxis, series };
+  }, []);
+
+  // New data goes to the chart that is there, with an animation
+  useEffect(() => {
+    if (result) {
+      result.xAxis.data.setAll(data);
+      result.series.data.setAll(data);
+    }
+  }, [result, data]);
+
+  return <div ref={ref} style={{ width: "100%", height: "500px" }}></div>;
 }
+```
 
-export default App
+## A chart from a JSON config
 
-## Updating the chart
+`<AmChart>` builds a chart from a [JSON config](https://www.amcharts.com/docs/v5/concepts/serializing/), with no chart code:
 
-You can update the chart by storing the amCharts objects inside of a `useRef`, and then using `useLayoutEffect` multiple times to update it:
+```typescript
+import { AmChart } from "@amcharts/amcharts5-react";
+import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";
 
-import { useRef, useLayoutEffect } from 'react';
-import \* as am5 from "@amcharts/amcharts5";
-import \* as am5xy from "@amcharts/amcharts5/xy";
-import am5themes\_Animated from "@amcharts/amcharts5/themes/Animated";
+<AmChart
+  config={config}
+  themes={[am5themes_Animated]}
+  style={{ height: "500px" }}
+  onReady={({ root, chart }) => { /* the chart is built */ }}
+/>
+```
 
-function Chart(props) {
-  const chartRef = useRef(null);
+| Prop | What it is |
+| --- | --- |
+| `config` | The chart as a JSON config: an object or a JSON string. A config with different content makes the chart again; the same content written inline on every render does not. |
+| `src` | A URL to load the config from, used when there is no `config`. |
+| `themes` | Theme classes, e.g. `[am5themes_Animated]`. Themes are not part of a config. |
+| `renderer` | `"svg"` draws the chart as SVG; the default is canvas. |
+| `onReady` | Called with `{ root, chart }` when the chart is built. |
+| `onError` | Called when it could not be built. |
+| `id`, `className`, `style` | For the chart's element. Without a height, it is 400 pixels high. |
 
-  // Creates the chart, this code only runs one time
-  useLayoutEffect(() => {
-    let root = am5.Root.new("chartdiv");
+It is the library's [`<am5-chart>` element](https://www.amcharts.com/docs/v5/getting-started/integrations/am5-chart-element/): a `ref` on it gives that element.
 
-    root.setThemes(\[
-      am5themes\_Animated.new(root)
-    \]);
+## Server rendering
 
-    let chart = root.container.children.push(
-      am5xy.XYChart.new(root, {
-        panY: false,
-        layout: root.verticalLayout
-      })
-    );
+Both work in pages rendered on a server: the library is loaded in the browser only. See [Next.js](https://www.amcharts.com/docs/v5/getting-started/integrations/next-js/) and [React Router](https://www.amcharts.com/docs/v5/getting-started/integrations/using-amcharts-5-with-remix/).
 
-    // Define data
-    let data = \[{
-      category: "Research",
-      value1: 1000,
-      value2: 588
-    }, {
-      category: "Marketing",
-      value1: 1200,
-      value2: 1800
-    }, {
-      category: "Sales",
-      value1: 850,
-      value2: 1230
-    }\];
-
-    // Create Y-axis
-    let yAxis = chart.yAxes.push(
-      am5xy.ValueAxis.new(root, {
-        renderer: am5xy.AxisRendererY.new(root, {})
-      })
-    );
+## License
 
-    // Create X-Axis
-    let xAxis = chart.xAxes.push(
-      am5xy.CategoryAxis.new(root, {
-    renderer: am5xy.AxisRendererX.new(root, {}),
-        categoryField: "category"
-      })
-    );
-    xAxis.data.setAll(data);
+With a commercial license, call `am5.addLicense()` once when the app starts, e.g. in `main.jsx`, before any chart is made. Not in your chart function: a chart decides on the logo when its root is made.
 
-    // Create series
-    let series1 = chart.series.push(
-      am5xy.ColumnSeries.new(root, {
-        name: "Series",
-        xAxis: xAxis,
-        yAxis: yAxis,
-        valueYField: "value1",
-        categoryXField: "category"
-      })
-    );
-    series1.data.setAll(data);
+## Without the package
 
-    let series2 = chart.series.push(
-      am5xy.ColumnSeries.new(root, {
-        name: "Series",
-        xAxis: xAxis,
-        yAxis: yAxis,
-        valueYField: "value2",
-        categoryXField: "category"
-      })
-    );
-    series2.data.setAll(data);
+To manage the chart yourself, create the root in an effect and dispose it in the effect's cleanup:
 
-    // Add legend
-    let legend = chart.children.push(am5.Legend.new(root, {}));
-    legend.data.setAll(chart.series.values);
+```typescript
+import { useLayoutEffect, useRef } from "react";
+import * as am5 from "@amcharts/amcharts5";
+import * as am5xy from "@amcharts/amcharts5/xy";
+import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";
 
-    // Add cursor
-    chart.set("cursor", am5xy.XYCursor.new(root, {}));
+function Chart({ data }) {
+  const chartdiv = useRef(null);
+
+  useLayoutEffect(() => {
+    const root = am5.Root.new(chartdiv.current);
+
+    root.setThemes([am5themes_Animated.new(root)]);
 
-    chartRef.current = chart;
+    const chart = root.container.children.push(
+      am5xy.XYChart.new(root, {})
+    );
+
+    // ... axes, series and data, as above
 
     return () => {
       root.dispose();
     };
-  }, \[\]);
-
-  // When the paddingRight prop changes it will update the chart
-  useLayoutEffect(() => {
-      chartRef.current.set("paddingRight", props.paddingRight);
-  }, \[props.paddingRight\]);
+  }, [data]);
 
-  return (
-    <div id="chartdiv" style={{ width: "500px", height: "500px" }}></div>
-  );
+  return <div ref={chartdiv} style={{ width: "100%", height: "500px" }}></div>;
 }
+
 export default Chart;
+```
 
-And then you can pass in props to the Chart component:
+## Examples
 
-<Chart paddingRight={20} />
+Example apps for Vite, Next.js, React Router and Astro are [on GitHub](https://github.com/amcharts/amcharts5/tree/master/integrations/react/examples).
 
-## Examples
+The sandboxes below create the chart without the package.
 
 ### Simple chart
 

package/extended/getting-started/integrations/remix-3.md

@@ -0,0 +1,88 @@
+---
+title: "Using amCharts 5 with Remix 3"
+source: "https://www.amcharts.com/docs/v5/getting-started/integrations/remix-3/"
+scraped: "2026-10-22"
+---
+
+amCharts 5 works with [Remix 3](https://remix.run/) through Remix's own tools: there is no separate package. For Remix 2, now React Router, see [React Router](https://www.amcharts.com/docs/v5/getting-started/integrations/using-amcharts-5-with-remix/).
+
+## A chart from a JSON config
+
+The simplest way: the library's [`<am5-chart>` element](https://www.amcharts.com/docs/v5/getting-started/integrations/am5-chart-element/). It needs no client code. Load its script files in your document's `<head>`, with the files for the chart types the config uses:
+
+```html
+<script src="https://cdn.amcharts.com/lib/5/index.js"></script>
+<script src="https://cdn.amcharts.com/lib/5/plugins/json.js"></script>
+<script src="https://cdn.amcharts.com/lib/5/element.js"></script>
+<script src="https://cdn.amcharts.com/lib/5/percent.js"></script>
+```
+
+Then render the element with its [JSON config](https://www.amcharts.com/docs/v5/concepts/serializing/). The server renders it like any HTML, and the browser builds the chart:
+
+```typescript
+function SalesPage() {
+  return () => (
+    <am5-chart config={JSON.stringify(config)} data-rmx-preserve-dom></am5-chart>
+  );
+}
+```
+
+`data-rmx-preserve-dom` keeps Remix's frame reloads from replacing what the element drew. Without a height, the element is 400 pixels high.
+
+## A chart written in code
+
+Make the chart's component a client entry, so it runs in the browser, and create the root with Remix's `ref` mixin. It gives you the element once it is on the page, and a signal that aborts when it is removed: dispose the root then.
+
+```typescript
+import { clientEntry, css, ref, type Handle } from "remix/component";
+
+export let SalesChart = clientEntry(
+  "/assets/sales-chart.js#SalesChart",
+  function SalesChart(handle: Handle<{ data: Array<{ category: string, value: number }> }>) {
+    return () => (
+      <div
+        data-rmx-preserve-dom
+        mix={[
+          css({ height: "400px" }),
+          ref(async (node, signal) => {
+            // In the browser only
+            const am5 = await import("@amcharts/amcharts5");
+            const am5percent = await import("@amcharts/amcharts5/percent");
+            if (signal.aborted) {
+              return;
+            }
+
+            const root = am5.Root.new(node as HTMLElement);
+
+            // The signal aborts when the element is removed
+            signal.addEventListener("abort", () => root.dispose());
+
+            const chart = root.container.children.push(
+              am5percent.PieChart.new(root, {})
+            );
+
+            const series = chart.series.push(
+              am5percent.PieSeries.new(root, {
+                valueField: "value",
+                categoryField: "category"
+              })
+            );
+
+            series.data.setAll(handle.props.data);
+          })
+        ]}
+      />
+    );
+  }
+);
+```
+
+-   The first argument of `clientEntry()` is where your build serves this module, with the export's name.
+-   The library is imported in the `ref` callback, which runs in the browser only, so the server never loads it.
+-   Props of client entries are serialized to JSON: pass data, not functions.
+
+For more on client entries and mixins, see Remix's [Hydration](https://github.com/remix-run/remix/blob/main/packages/component/docs/hydration.md) and [Mixins](https://github.com/remix-run/remix/blob/main/packages/component/docs/mixins.md) guides.
+
+## License
+
+With a commercial license, call `am5.addLicense()` before the chart is made: in a script after `index.js`, or in the `ref` callback before `am5.Root.new()`.

package/extended/getting-started/integrations/remix.md

@@ -0,0 +1,55 @@
+---
+title: "Using amCharts 5 with Remix"
+source: "https://www.amcharts.com/docs/v5/getting-started/integrations/remix/"
+scraped: "2026-10-22"
+---
+
+Remix 2 is now [React Router](https://reactrouter.com/), in its framework mode. This tutorial shows amCharts 5 in a React Router app. For Remix 3, see [Remix 3](https://www.amcharts.com/docs/v5/getting-started/integrations/remix-3/).
+
+Create a project and install amCharts with our React package:
+
+```shell
+npx create-react-router@latest my-project
+cd my-project
+npm install @amcharts/amcharts5 @amcharts/amcharts5-react
+```
+
+React Router renders pages on the server with Node, which cannot load amCharts' files on its own. Add amCharts to the server build in `vite.config.ts`:
+
+```typescript
+import { defineConfig } from "vite";
+import { reactRouter } from "@react-router/dev/vite";
+
+export default defineConfig({
+  plugins: [reactRouter()],
+  ssr: {
+    noExternal: ["@amcharts/amcharts5"]
+  }
+});
+```
+
+Then use `useAmChart()` and `<AmChart>` in a route, e.g. `app/routes/home.tsx`. There is no need for a `.client.tsx` file or `ClientOnly`: the package loads the library in the browser only.
+
+```typescript
+import { useAmChart, AmChart } from "@amcharts/amcharts5-react";
+import * as am5xy from "@amcharts/amcharts5/xy";
+import config from "../chart-config.json";
+
+export default function Home() {
+  const { ref } = useAmChart((root) => {
+    const chart = root.container.children.push(am5xy.XYChart.new(root, {}));
+    // ... axes, series and data
+  }, []);
+
+  return (
+    <>
+      <div ref={ref} style={{ height: "500px" }}></div>
+      <AmChart config={config} style={{ height: "500px" }} />
+    </>
+  );
+}
+```
+
+See the [React tutorial](https://www.amcharts.com/docs/v5/getting-started/integrations/react/) for everything the package does, and the [example app](https://github.com/amcharts/amcharts5/tree/master/integrations/react/examples/react-router) on GitHub.
+
+NOTE Astro needs the same setting, under `vite` in `astro.config.mjs`.

package/extended/getting-started/integrations/sveltekit.md

@@ -0,0 +1,120 @@
+---
+title: "Using amCharts 5 with SvelteKit"
+source: "https://www.amcharts.com/docs/v5/getting-started/integrations/sveltekit/"
+scraped: "2026-10-22"
+---
+
+Use amCharts 5 in Svelte and [SvelteKit](https://svelte.dev/docs/kit) with our [`@amcharts/amcharts5-svelte`](https://www.npmjs.com/package/@amcharts/amcharts5-svelte) package. It creates and disposes the chart with the element, and works with server rendering: nothing has to be configured.
+
+Create a project, if you do not have one, and install amCharts with the package:
+
+```shell
+npx sv create my-app
+cd my-app
+npm install @amcharts/amcharts5 @amcharts/amcharts5-svelte
+```
+
+It needs Svelte 4 or later and amCharts 5.21.0 or later.
+
+## Using the package
+
+In Svelte 5.29 or later, use attachments. `attachAmChart()` gives your function a new root in the element; build the chart in it as in any amCharts example. `attachAmChartConfig()` builds a chart from a [JSON config](https://www.amcharts.com/docs/v5/concepts/serializing/) in the library's [`<am5-chart>` element](https://www.amcharts.com/docs/v5/getting-started/integrations/am5-chart-element/). Both elements need a height.
+
+```html
+<script lang="ts">
+  import { attachAmChart, attachAmChartConfig } from "@amcharts/amcharts5-svelte";
+  import type { Root } from "@amcharts/amcharts5";
+  import * as am5xy from "@amcharts/amcharts5/xy";
+  import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";
+
+  let { data, config } = $props();
+
+  // The series, to give it new data later
+  let series = $state.raw<am5xy.ColumnSeries>();
+
+  function buildChart(root: Root) {
+    root.setThemes([am5themes_Animated.new(root)]);
+
+    const chart = root.container.children.push(am5xy.XYChart.new(root, {}));
+
+    const xAxis = chart.xAxes.push(am5xy.CategoryAxis.new(root, {
+      categoryField: "category",
+      renderer: am5xy.AxisRendererX.new(root, {})
+    }));
+
+    const yAxis = chart.yAxes.push(am5xy.ValueAxis.new(root, {
+      renderer: am5xy.AxisRendererY.new(root, {})
+    }));
+
+    series = chart.series.push(am5xy.ColumnSeries.new(root, {
+      xAxis: xAxis,
+      yAxis: yAxis,
+      categoryXField: "category",
+      valueYField: "value"
+    }));
+  }
+
+  // The data goes to the chart once it is made, and again when it changes,
+  // without making the chart again
+  $effect(() => {
+    if (series) {
+      const rows = $state.snapshot(data);
+      series.get("xAxis").data.setAll(rows);
+      series.data.setAll(rows);
+    }
+  });
+</script>
+
+<div {@attach attachAmChart(buildChart)} style="height: 500px"></div>
+
+<am5-chart {@attach attachAmChartConfig({ config, themes: [am5themes_Animated] })} style="height: 500px"></am5-chart>
+```
+
+-   The chart is made when the element is there, and disposed when it goes. Like any attachment, it is made again when state read in its expression changes.
+-   `attachAmChart(buildChart, { renderer: "svg" })` draws the chart as SVG.
+-   `attachAmChart(buildChart, { onError })` gets errors from your function. Without it, they are reported as uncaught errors.
+-   Give amCharts plain data: `$state.snapshot()` turns Svelte state into it.
+-   The `<am5-chart>` element dispatches `ready` (`event.detail` has `root` and `chart`) and `error`: listen with `onready` and `onerror`.
+
+### Svelte 4 and older Svelte 5
+
+Use the actions instead. With `deps`, the chart is made again when a value in it changes, compared by content:
+
+```html
+<div use:amChart={{ setup: buildChart, deps: [data] }} style="height: 500px"></div>
+
+<am5-chart use:amChartConfig={{ config }} on:ready={(event) => console.log(event.detail.chart)}></am5-chart>
+```
+
+### License
+
+With a commercial license, call `am5.addLicense()` once in `src/hooks.client.ts`, which runs when the app starts in the browser.
+
+An [example app](https://github.com/amcharts/amcharts5/tree/master/integrations/svelte/examples/sveltekit) is on GitHub.
+
+## Without the package
+
+To manage the chart yourself, create the root in `onMount` and dispose it in the function it returns. `onMount` runs in the browser only:
+
+```html
+<script>
+  import { onMount } from "svelte";
+  import * as am5 from "@amcharts/amcharts5";
+  import * as am5xy from "@amcharts/amcharts5/xy";
+
+  let chartdiv;
+
+  onMount(() => {
+    const root = am5.Root.new(chartdiv);
+
+    const chart = root.container.children.push(am5xy.XYChart.new(root, {}));
+    // ... axes, series and data
+
+    return () => {
+      root.dispose();
+    };
+  });
+</script>
+
+<div bind:this={chartdiv} style="height: 500px"></div>
+```