> For the complete documentation index, see [llms.txt](https://docs.rowsncolumns.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rowsncolumns.app/configuration/features/charts.md).

# Charts

Spreadsheet ships a rich chart pipeline with full XLSX + ODS round-trip on every supported chart type. The render backend is ECharts by default; Plotly is available as an opt-in (`@rowsncolumns/charts/plotly/basic-chart`).

## Supported chart types

All round-trip via XLSX import + export unless noted.

| Type                         | Notes                                                                                                                                 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Column (clustered / stacked) |                                                                                                                                       |
| Bar (clustered / stacked)    |                                                                                                                                       |
| Line (smooth / stepped)      |                                                                                                                                       |
| Area                         |                                                                                                                                       |
| Pie / doughnut               |                                                                                                                                       |
| Scatter                      |                                                                                                                                       |
| Bubble                       | Size dimension on top of scatter                                                                                                      |
| Radar                        |                                                                                                                                       |
| Treemap                      |                                                                                                                                       |
| Sunburst                     |                                                                                                                                       |
| Stock (line-derived)         | OHLC / candlestick variants deferred                                                                                                  |
| Waterfall                    | Emitted as `c15:waterfallChart` in `mc:Choice` + `c:barChart` fallback — Excel 2016+ renders natively, older Excel falls back to bars |
| Funnel                       | Same `c15:funnelChart` / fallback shape                                                                                               |
| Histogram                    | Auto/Sturges binning + bin-count override                                                                                             |
| Box & whisker                | quartileMethod, showMean, showOutlier                                                                                                 |
| Combo (mixed series)         | Per-series `seriesChartType` picker                                                                                                   |
| Dual-axis                    | `secondaryValueAxisOptions` round-trips                                                                                               |

Not yet supported: 3D variants (bar3D / column3D / pie3D / line3D / area3D), surface, OHLC / candlestick stock. These need `echarts-gl` and are deferred.

## Chart features

Every chart supports:

* **Titles, legends, axis labels** — formula-driven titles & labels (range references resolved at render)
* **Data labels** — value / category / percent
* **Trendlines** — linear, polynomial, exponential, log
* **Error bars** — value / percentage / stdev / custom
* **Data label styles** — number formats applied per series
* **Series colors** — per series + theme accents
* **Series gradient fills** — linear (with `degree`) and path (with `left`/`right`/`top`/`bottom` insets). Mirrors OOXML `<a:gradFill>` inside `<c:spPr>`. Set `series[].gradient` on the chart spec.
* **Negative-value coloring** — `invertIfNegative` + `negativeColor` on bar/column series
* **Chart move + resize** with anchor cell + pixel offsets
* **Chart editing UI** — `ChartEditorDialog` + `ChartEditor` components

## Installation

```bash
npm install @rowsncolumns/charts
```

ECharts is a peer dependency for the default backend:

```bash
npm install echarts echarts-for-react
```

For Plotly:

```bash
npm install @rowsncolumns/charts plotly.js react-plotly.js
```

## Basic usage

Wire charts through the `useCharts` hook (`@rowsncolumns/charts`) and pass the resulting handlers to `CanvasGrid`:

```tsx
import { useCharts, ChartEditorDialog, ChartEditor } from "@rowsncolumns/charts";

const App = () => {
  const [charts, onChangeCharts] = useState<EmbeddedChart[]>([]);

  const {
    onRequestEditChart,
    onDeleteChart,
    onMoveChart,
    onResizeChart,
    onUpdateChart,
    onCreateChart,
    selectedChart,
  } = useCharts({
    createHistory,
    onChangeCharts,
    getFormattedValue,
    getEffectiveValue,
  });

  return (
    <SpreadsheetProvider>
      <CanvasGrid
        charts={charts}
        onMoveChart={onMoveChart}
        onResizeChart={onResizeChart}
        onDeleteChart={onDeleteChart}
        onRequestEditChart={onRequestEditChart}
      />
      <ChartEditorDialog>
        <ChartEditor
          chart={selectedChart}
          onUpdate={onUpdateChart}
        />
      </ChartEditorDialog>
    </SpreadsheetProvider>
  );
};
```

## Series gradient fills

Set `gradient` on any series — overrides `color`:

```ts
const chart: EmbeddedChart = {
  chartId: "c1",
  position: { /* … */ },
  spec: {
    chartType: "column",
    title: "Q1 Sales",
    domains: [{ sources: [/* category range */] }],
    series: [
      {
        dataLabel: "Revenue",
        gradient: {
          type: "linear",
          degree: 90,
          stops: [
            { position: 0, color: "#fde68a" },
            { position: 1, color: "#dc2626" },
          ],
        },
        sources: [/* value range */],
      },
    ],
  },
};
```

For radial fills use `type: "path"` with `left` / `right` / `top` / `bottom` insets (0..1 each):

```ts
gradient: {
  type: "path",
  left: 0.5,
  right: 0.5,
  top: 0.5,
  bottom: 0.5,
  stops: [
    { position: 0, color: "#ffffff" },
    { position: 1, color: "#7c3aed" },
  ],
}
```

ODS export emits the equivalent `<draw:gradient>` definition; XLSX export emits `<a:gradFill>` inside `<c:spPr>`.

## Bringing your own renderer

The default ECharts component is bundled, but charts are agnostic of the rendering layer. Pass your own component via the chart prop pipeline — the spec data flow is independent.

For an alternative renderer, import a different chart component (e.g. `import "@rowsncolumns/charts/plotly/basic-chart"`) — the spec format is identical.