@servicetitan/carto-charts-react

Web chart host for Carto: a thin declarative <Chart> over echarts-for-react with the SVG renderer, rendering the platform-neutral option specs and theme from @servicetitan/carto-charts-core.

Status: early release. Charts have no overlay component yet (ANV-5332).

import { Chart } from "@servicetitan/carto-charts-react";
import "@servicetitan/carto-charts-react/styles.css";
import type { EChartsOption } from "echarts";

// Consumer-authored option — chart type + data live in your app, not the DS.
const option: EChartsOption = {
  xAxis: { type: "category", data: ["North", "South", "East", "West"] },
  yAxis: { type: "value" },
  series: [{ type: "bar", data: [1200, 980, 1450, 1100] }],
};

<Chart option={option} width={480} height={300} />;

Note what that option does not contain: no colors, borders, patterns, marker shapes or corner radii. Those come from variant, which defaults to "monochrome". You should not be hand-authoring per-series styling to get Carto's look — if you find yourself doing that, something is missing here.

Props

• option — an ECharts option spec (the same object works on React Native).

• variant — "monochrome" (default) or "categorical". The whole treatment, not just a color list: palette, monochrome's borders and pattern fills, line marker shapes, bar corner radius. Monochrome has four designed steps and is scoped to 4 variables or fewer; categorical is for 5+, and is what line charts use at any count. Anything your option specifies wins over it.

• appearance — "light" (default) or "dark". Charts don't detect this: this package doesn't depend on the kits, so no CartoTheme is in reach. Inside one, read it with carto-react-kit's useCartoTheme and pass it through.

• width / height — explicit pixel dimensions, the same props the React Native host takes, so sizing code reads the same on both platforms. Optional here: unlike native, a web chart has a container to fill.

• className — for sizing pixels can't express (percentages, container queries, aspect ratios). There is no style prop.

• renderTooltip — renders the tooltip's content. Omit it and the chart has no tooltip; there's no built-in content, since formatting a value is a product decision. Content only — the chart tracks the pointer and keeps the tooltip inside the plot. Wrap it in TooltipSurface from @servicetitan/carto-react-kit for the Carto pill:

  renderTooltip={({ name, points }) => (
    <TooltipSurface content={`${name}: ${points[0]?.value}`} />
  )}

  points is one entry for a bar, slice or marked line. An area or marker-less line has nothing to hover, so it reports every series at the category instead.

• theme — escape hatch. A registered theme name or inline theme object, for a genuinely custom theme; it replaces what appearance/variant would build. Note it replaces only the theme half of a variant — the per-index treatment still follows variant.

Sizing precedence is width/height → className → fluid default. Passing the props wins over a class, since asking for a pixel size is explicit; omitting them leaves the chart filling its container, which a class can then override.

Semantic status colors

variant covers the two index-cycled palettes. Semantic status colors are chosen by meaning and urgency rather than by series index, so you compose them yourself from chartPalette(appearance, "semantic") and chartStepItemStyle — see @servicetitan/carto-charts-core and the @servicetitan/carto-charts-react/Semantic stories in carto-react-kit's Storybook.

Setup

styles.css is a required import, the same contract @servicetitan/carto-react-kit/styles.css has: the styles compile to their own artifact, so importing only the component leaves the container unstyled.

echarts and react are peer dependencies. The SVG renderer is fixed for the accessibility posture — real SVG nodes plus the option's aria description, which this host enables by default.