> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Learn the basics of amCharts 5 and how to apply Anvil2 themes to your charts in React.

> [!WARNING]
>
> Charts (amCharts) is deprecated. Use [Charts - React](https://anvil.servicetitan.com/docs/charts/web)
> or [Charts - React Native](https://anvil.servicetitan.com/docs/charts/react-native) for any new chart
> experiences.

This guide covers the amCharts 5 fundamentals you need to create charts with Anvil2 themes. amCharts 5 is an imperative DOM-based library, so using it in React requires manual lifecycle management that differs from typical React component patterns.

> [!NOTE]
>
> For comprehensive amCharts 5 documentation, visit [amcharts.com/docs/v5](https://www.amcharts.com/docs/v5/).

## amCharts 5 core concepts

### The root element

Every amCharts 5 chart starts with a **root element**. The root manages the chart lifecycle and is required to create every other amCharts object. Create it by passing the ID of a container `<div>`:

```tsx theme={null}
import * as am5 from "@amcharts/amcharts5";

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

### The `.new()` pattern

amCharts 5 uses a static `.new()` method instead of the `new` keyword to create instances. The first argument is always the root element:

```tsx theme={null}
// Create a chart
const chart = am5percent.PieChart.new(root, {
  layout: root.horizontalLayout,
  innerRadius: am5.percent(50),
});

// Create a series
const series = am5percent.PieSeries.new(root, {
  valueField: "value",
  categoryField: "category",
});
```

### Setting data

Use `setAll()` to bind data to a series. Pass an array of objects where keys match the field names you configured on the series:

```tsx theme={null}
series.data.setAll([
  { category: "Category A", value: 501 },
  { category: "Category B", value: 302 },
  { category: "Category C", value: 201 },
]);
```

### Themes

Themes control the visual appearance of chart elements. Pass structure (series, axes, data) and let the theme supply colors. Do not hardcode hex values in chart options. Apply themes to the root using `setThemes()`. You can combine multiple themes, and order matters — later themes override earlier ones:

```tsx theme={null}
import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";
import { ThemeMonochrome } from "@servicetitan/anvil2-ext-charts/am5";

root.setThemes([
  am5themes_Animated.new(root),  // Adds animations
  ThemeMonochrome.new(root),     // Applies Anvil2 styles
]);
```

## Using Anvil2 themes in React

### Basic setup pattern

amCharts 5 manages its own DOM, which does not fit naturally into React's rendering model. Create the root in a `useLayoutEffect` and dispose of it on cleanup to prevent memory leaks.

In React Strict Mode, effects can run twice in development, so it's important to dispose the chart root in the cleanup function to avoid duplicate chart instances and visual glitches:

ext-charts-donut-basic

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/ext-charts-donut-basic?file=src/App.tsx)

```tsx lines expandable theme={null}
import { useLayoutEffect } from "react";
import * as am5 from "@amcharts/amcharts5";
import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";
import * as am5percent from "@amcharts/amcharts5/percent";
import { ThemeMonochrome } from "@servicetitan/anvil2-ext-charts/am5";

function App() {
  useLayoutEffect(() => {
    const data = [
      { category: "Lithuania", value: 501.9 },
      { category: "Czechia", value: 301.9 },
      { category: "Ireland", value: 201.1 },
      { category: "Germany", value: 165.8 },
    ];

    const root = am5.Root.new("chartdiv");
    root.setThemes([am5themes_Animated.new(root), ThemeMonochrome.new(root)]);

    const chart = root.container.children.push(
      am5percent.PieChart.new(root, {
        layout: root.horizontalLayout,
        innerRadius: am5.percent(50),
      }),
    );

    const series = chart.series.push(
      am5percent.PieSeries.new(root, {
        name: "Series",
        valueField: "value",
        categoryField: "category",
        legendValueText: "",
      }),
    );

    // Display percentage labels on slices
    series.labels.template.set(
      "text",
      "{valuePercentTotal.formatNumber('#.')}%",
    );

    series.data.setAll(data);

    return () => root.dispose();
  }, []);

  return <div id="chartdiv" style={{ minWidth: "55rem", height: "500px" }} />;
}

export default App;
```

### Switching themes

To use a different Anvil2 theme, swap the import:

```tsx theme={null}
// Monochrome — ordered/progressive data (default, 4 or fewer variables)
import { ThemeMonochrome } from "@servicetitan/anvil2-ext-charts/am5";

// Categorical — 5+ distinct categories
import { ThemeCategorical } from "@servicetitan/anvil2-ext-charts/am5";

// Semantic — status-based data (success, neutral, warning, danger)
import { ThemeSemantic } from "@servicetitan/anvil2-ext-charts/am5";
```

### Combining with amCharts built-in themes

Combine the Anvil2 themes with amCharts built-in themes for additional functionality. The `Animated` theme adds smooth transitions:

```tsx theme={null}
import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";
import { ThemeCategorical } from "@servicetitan/anvil2-ext-charts/am5";

root.setThemes([
  am5themes_Animated.new(root),
  ThemeCategorical.new(root),   // Applied last so Anvil2 styles take precedence
]);
```

> [!WARNING]
>
> Theme order matters. The Anvil2 theme must come after amCharts built-in themes in the array. If you place it first, the built-in theme will override Anvil2's color palette, tooltip styling, and other rules.

### Chart placement

Wrap each chart in one Card. Place the title inside the Card. Do not add a duplicate heading above the Card. See [Card](https://anvil.servicetitan.com/docs/components/card/design).

## Chart modules

amCharts 5 organizes chart types into separate modules to keep bundle sizes small. Import only the modules you need:

| Module | Import | Chart types |
| - | - | - |
| **Core** | `@amcharts/amcharts5` | Root, Legend, Tooltip, Label, ColorSet |
| **Percent** | `@amcharts/amcharts5/percent` | PieChart, PieSeries (donut/pie charts) |
| **XY** | `@amcharts/amcharts5/xy` | XYChart, ColumnSeries, CategoryAxis, ValueAxis (bar charts) |
| **Themes** | `@amcharts/amcharts5/themes/Animated` | Built-in animation theme |

## Next steps

* [Bar Charts](https://anvil.servicetitan.com/docs/charts/amcharts/bar-charts.md) — Vertical, horizontal, grouped, and stacked bar chart examples
* [Donut Charts](https://anvil.servicetitan.com/docs/charts/amcharts/donut-charts.md) — Pie and donut chart examples with legends
* [Data Visualization Guidelines](https://anvil.servicetitan.com/docs/data-visualization) — Design guidelines for color palettes, variable ordering, and chart anatomy
* [amCharts 5 Documentation](https://www.amcharts.com/docs/v5/) — Full amCharts 5 reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.