> ## 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.

# Chart Component

> Implement the Chart component from @servicetitan/anvil2-charts-kit.

**Implementation**

charts-react-minimal

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

```tsx lines expandable theme={null}
import { Chart, type EChartsOption } from "@servicetitan/anvil2-charts-kit";
import "@servicetitan/anvil2-charts-kit/styles.css";

function App() {
  const option: EChartsOption = {
    xAxis: { type: "category", data: ["North", "South", "East", "West"] },
    yAxis: { type: "value" },
    series: [{ type: "bar", data: [1200, 980, 1450, 1100] }],
  };

  return (
    <Chart
      option={option}
      width={480}
      height={300}
      accessibilityLabel="Bar chart. Sales by region."
    />
  );
}

export default App;
```

## Common Examples

The `Chart` component renders an ECharts option with Anvil2 styling. Import `EChartsOption` from the kit to keep chart configuration on the supported public API.

```tsx theme={null}
import {
  Chart,
  type EChartsOption,
} from "@servicetitan/anvil2-charts-kit";
import "@servicetitan/anvil2-charts-kit/styles.css";

const option: EChartsOption = {
  xAxis: { type: "category", data: ["North", "South", "East", "West"] },
  yAxis: { type: "value" },
  series: [{ type: "bar", data: [1200, 980, 1450, 1100] }],
};

function ExampleComponent() {
  return (
    <Chart
      option={option}
      accessibilityLabel="Bar chart. Sales by region."
    />
  );
}
```

`Chart` defaults to `appearance="light"` and `variant="monochrome"`. Set `appearance` to match the surrounding theme.

The chart graphic is hidden from assistive technology. For supported option shapes, `Chart` exposes the data as a visually hidden table instead. Use `accessibilityLabel` for its caption; it falls back to `option.title.text`, then `"Chart"`.

Direct category-axis data for bar, line, and area series and direct pie or donut data are supported. Dataset transforms and other option shapes fall back to the accessible label.

## Tooltips

Pass `renderTooltip` to provide visual tooltip content. The chart controls placement and keeps a gap from the pointer. When the plot is shorter than the tooltip, the gap wins and the tooltip extends outside the chart box. Tooltips are hidden from assistive technology because the table exposes the values.

charts-react-tooltip

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

```tsx lines expandable theme={null}
import {
  Chart,
  type ChartTooltipInfo,
  type EChartsOption,
} from "@servicetitan/anvil2-charts-kit";
import "@servicetitan/anvil2-charts-kit/styles.css";
import { CartoTheme, Text, TooltipSurface } from "@servicetitan/anvil2-ai-kit";
// This file is most likely already in your workspace
import "@servicetitan/anvil2-ai-kit/styles.css";

function renderTooltip({ name, points }: ChartTooltipInfo) {
  return (
    <TooltipSurface
      content={
        <>
          <Text text={name} />
          {points.map((point) => (
            <Text
              key={point.seriesIndex}
              text={`${point.seriesName ? `${point.seriesName}: ` : ""}${String(point.value)}`}
            />
          ))}
        </>
      }
    />
  );
}

function App() {
  const option: EChartsOption = {
    grid: { left: 48, right: 16, top: 24, bottom: 32 },
    xAxis: { type: "category", data: ["North", "South", "East", "West"] },
    yAxis: { type: "value" },
    series: [{ type: "bar", data: [1200, 980, 1450, 1100] }],
  };

  return (
    <CartoTheme>
      <Chart
        option={option}
        variant="monochrome"
        renderTooltip={renderTooltip}
        width={480}
        height={300}
        accessibilityLabel="Bar chart. Sales by region."
      />
    </CartoTheme>
  );
}

export default App;
```

Omit `renderTooltip` when the chart does not need a tooltip. Format each `value` for its product context.

## Selection

Selection is enabled by default for bars, segments, slices, line points, and area bands. A line drawn without point markers is not selectable. Clicking an area band selects its point at the nearest category. Selecting a mark changes it to the selection color and fades every other mark to 20% opacity. Select the active mark again or click an empty plot area to clear it. Keyboard and screen-reader users select the matching value in the data table.

Omit `selected` to let `Chart` own selection. Use `onSelectedChange` to respond when the active mark changes. Pass both props to control selection from product state.

charts-react-selection

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

```tsx lines expandable theme={null}
import {
  Chart,
  type ChartTooltipInfo,
  type EChartsOption,
} from "@servicetitan/anvil2-charts-kit";
import "@servicetitan/anvil2-charts-kit/styles.css";
import { CartoTheme, Text } from "@servicetitan/anvil2-ai-kit";
// This file is most likely already in your workspace
import "@servicetitan/anvil2-ai-kit/styles.css";
import { useState } from "react";

function App() {
  const [selectedInfo, setSelectedInfo] = useState<ChartTooltipInfo | null>(
    null,
  );
  const point = selectedInfo?.points[0];

  const option: EChartsOption = {
    grid: { left: 48, right: 16, top: 24, bottom: 32 },
    xAxis: { type: "category", data: ["North", "South", "East", "West"] },
    yAxis: { type: "value" },
    series: [{ type: "bar", data: [1200, 980, 1450, 1100] }],
  };

  return (
    <CartoTheme>
      <Chart
        option={option}
        selected={
          point
            ? {
                seriesIndex: point.seriesIndex,
                dataIndex: point.dataIndex,
              }
            : null
        }
        onSelectedChange={setSelectedInfo}
        width={480}
        height={300}
        accessibilityLabel="Bar chart. Sales by region."
      />
      <Text
        text={
          selectedInfo && point
            ? `${selectedInfo.name} · ${String(point.value)}`
            : "Select a bar to keep it active."
        }
      />
    </CartoTheme>
  );
}

export default App;
```

A controlled `selected` value identifies the mark by `seriesIndex` and `dataIndex`. `onSelectedChange` receives `ChartTooltipInfo` so the product can read the selected category and value without resolving those indices again. Set `selectedMode: false` on a series that must not support selection.

## Data point clicks

Pass `onDataPointClick` to handle activation of a data mark. Pointer users click the plot; keyboard and screen-reader users Tab to the data table and activate a value cell. The callback receives the same `ChartTooltipInfo` a tooltip does: `name` identifies the category, and `points[0]` describes the mark. Clicks on empty plot area, axis labels, legend entries, and the title are ignored. Omit the callback when the product does not need an additional click action; value cells remain interactive for selection. Dataset transforms and other unsupported option shapes produce no table; `onDataPointClick` is not supported for those shapes.

charts-react-click

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

```tsx lines expandable theme={null}
import {
  Chart,
  type ChartTooltipInfo,
  type EChartsOption,
} from "@servicetitan/anvil2-charts-kit";
import "@servicetitan/anvil2-charts-kit/styles.css";
import { CartoTheme, Text } from "@servicetitan/anvil2-ai-kit";
// This file is most likely already in your workspace
import "@servicetitan/anvil2-ai-kit/styles.css";
import { useState } from "react";

function App() {
  const [selected, setSelected] = useState<ChartTooltipInfo | null>(null);
  const point = selected?.points[0];

  const option: EChartsOption = {
    grid: { left: 48, right: 16, top: 24, bottom: 32 },
    xAxis: { type: "category", data: ["North", "South", "East", "West"] },
    yAxis: { type: "value" },
    series: [{ type: "bar", data: [1200, 980, 1450, 1100] }],
  };

  return (
    <CartoTheme>
      <Chart
        option={option}
        variant="monochrome"
        width={480}
        height={300}
        accessibilityLabel="Bar chart. Sales by region."
        onDataPointClick={({ name, points }) => setSelected({ name, points })}
      />
      <Text
        text={
          selected && point
            ? `${selected.name} · ${String(point.value)}`
            : "Click a bar, or Tab to the data table and press Enter, to report its category and value."
        }
      />
    </CartoTheme>
  );
}

export default App;
```

Hold the reported mark in state to open a Dialog, reveal a detail panel, or navigate. See [Stacked bar](https://anvil.servicetitan.com/docs/charts/web/stacked-bar.md#data-point-clicks) for a segment-level example.

## Palette utilities

Use `variant` when colors follow the palette's index order. The variant applies fills, borders, patterns, markers, corner treatments, and hover behavior.

```tsx theme={null}
<Chart option={option} variant="categorical" />
```

Use `chartPalette` when an option needs a specific palette entry. `chartStepItemStyle` converts monochrome and semantic steps into ECharts `itemStyle` values.

```tsx theme={null}
import {
  chartPalette,
  chartStepItemStyle,
} from "@servicetitan/anvil2-charts-kit";

const palette = chartPalette("light", "semantic");

const option: EChartsOption = {
  series: [
    {
      type: "bar",
      data: [1200],
      itemStyle: chartStepItemStyle(palette.danger.primary),
    },
  ],
};
```

Consumer-defined `itemStyle` values override variant styling.

**Agent guidance**

* Define chart structure and data in the ECharts `option`.
* Set `accessibilityLabel` to name the chart's hidden data table.
* Import `EChartsOption`, chart types, and palette utilities from `@servicetitan/anvil2-charts-kit`.
* Use `variant` when colors follow palette order.
* Use `chartPalette` and `chartStepItemStyle` only when the option requires a specific palette entry.
* Do not hard-code Anvil colors, borders, decals, marker shapes, or bar radii.
* Do not add an ECharts `tooltip` block. Use `renderTooltip`.
* Return tooltip content only. The chart controls tooltip placement.
* Selection is enabled by default. Use `selected` and `onSelectedChange` when product state controls the active mark.
* Use `onDataPointClick` to handle activation of a data mark. Pointer users click the plot; keyboard and screen-reader users activate the data table. Do not add ECharts event handlers to the option. The callback is not supported when the option produces no table (`dataset` and other unsupported shapes).
* Supported series are bar, line, area, pie, and donut. Registered series can be combined in one option.

**Chart Props**

```tsx theme={null}
<Chart
  option={option}
  accessibilityLabel="Bar chart. Sales by region."
  variant="monochrome"
  width={480}
  height={300}
/>
```

## `Chart` Props

**option** `EChartsOption` *required*

Defines chart structure and data.

**accessibilityLabel** `string`

Sets the caption for the visually hidden data table. Falls back to `option.title.text`, then `"Chart"`.

**appearance** `"light" | "dark"` (default: light)

Sets the token appearance used by the chart theme.

**className** `string`

Applies sizing or layout styles that pixel dimensions cannot express. `width` and `height` take precedence.

**height** `number`

Sets an explicit height in pixels. The fluid default uses the parent height or a 300px minimum.

**onDataPointClick** `(info: ChartTooltipInfo) =\> void`

Handles activation of a data mark from a plot click or from a value cell in the data table. Not supported when the option produces no table.

**onSelectedChange** `(info: ChartTooltipInfo | null) =\> void`

Handles selection changes. Receives `null` when the active mark is cleared.

**renderTooltip** `(info: ChartTooltipInfo) =\> ReactNode`

Renders visual-only content for the active data point.

**selected** `ChartSelection | null`

Controls the active mark. Omit this prop to let the chart own selection.

**theme** `string | object`

Replaces the chart theme with a registered theme name or inline theme object.

**variant** `"monochrome" | "categorical"` (default: monochrome)

Applies an index-ordered palette and chart treatment.

**width** `number`

Sets an explicit width in pixels. The fluid default fills the container width.

**Selection Config**

```tsx theme={null}
import type { ChartSelection } from "@servicetitan/anvil2-charts-kit";
```

## `ChartSelection`

`ChartSelection` identifies one mark in `option.series`.

**dataIndex** `number` *required*

Identifies the value within the selected series data.

**seriesIndex** `number` *required*

Identifies the selected series within `option.series`.

**Tooltip Config**

```tsx theme={null}
import type { ChartTooltipInfo } from "@servicetitan/anvil2-charts-kit";
```

## `ChartTooltipInfo`

`renderTooltip` receives the active category and its data points. `onDataPointClick` and `onSelectedChange` receive one activated mark in the same shape. `onSelectedChange` receives `null` when selection clears.

**name** `string` *required*

Identifies the active category or donut slice.

**points** `ChartTooltipPoint[]` *required*

Contains the active data point for each applicable series.

**Tooltip Point Config**

```tsx theme={null}
import type { ChartTooltipPoint } from "@servicetitan/anvil2-charts-kit";
```

## `ChartTooltipPoint`

`ChartTooltipPoint` describes one series value in a tooltip.

**color** `string | undefined` *required*

Provides the resolved color when the chart can represent it as a swatch.

**dataIndex** `number` *required*

Identifies the value within the series data.

**seriesIndex** `number` *required*

Identifies the series within `option.series`.

**seriesName** `string | undefined` *required*

Provides the series `name` when defined.

**value** `unknown` *required*

Provides the datum value for product-specific formatting.


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