# Chart

- Human documentation: [https://docs.univer.ai/reference/facade/chart](https://docs.univer.ai/reference/facade/chart)

- Agent Markdown: [https://docs.univer.ai/reference/facade/chart.md](https://docs.univer.ai/reference/facade/chart.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/chart.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/chart.mdx)

---

| Packages | `@univerjs-pro/engine-chart`, `@univerjs-pro/sheets-chart`, `@univerjs-pro/slides-chart`, `@univerjs-pro/boards-chart`, `@univerjs-pro/docs-chart`, `@univerjs-pro/chart-ui` |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

Charts use direct host Facade methods. Create detached chart information with `newChart(type)`, insert it with `insertChart(info)`, and then edit the returned live `FChart`.

> Import `@univerjs-pro/engine-chart/facade` and the matching host facade. Import `@univerjs-pro/chart-ui/facade` to add image export.

## Host lifecycle

| Host   | Create and insert                                | Read                          |
| ------ | ------------------------------------------------ | ----------------------------- |
| Sheets | `FWorksheet.newChart(type)`, `insertChart(info)` | `getChart(id)`, `getCharts()` |
| Slides | `FSlide.newChart(type)`, `insertChart(info)`     | `getChart(id)`, `getCharts()` |
| Boards | `FBoard.newChart(type)`, `insertChart(info)`     | `getChart(id)`, `getCharts()` |
| Docs   | `FDocument.newChart(type)`, `insertChart(info)`  | `getChart(id)`, `getCharts()` |

`newChart()` returns a type-specific builder. It does not mutate the host until `build()` is passed to `insertChart()`.

## Sheets example

```ts
const workbook = univerAPI.getActiveWorkbook()
if (!workbook) throw new Error('No active workbook')

const worksheet = workbook.getActiveSheet()
const info = worksheet
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    range: 'A1:D6',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
  })
  .setPosition('F2')
  .setSize(640, 360)
  .setCategoryField(0)
  .setValueFields([1, 2, 3])
  .setTitle('Quarterly revenue')
  .build()

const chart = await worksheet.insertChart(info)
chart.setTitle('Quarterly revenue (updated)').bringToFront()
```

Use `getChart(id)` or `getCharts()` to resolve live charts. Common setters update an inserted chart immediately; `setDataSource()`, `update()`, `remove()`, and image export are asynchronous.

```ts
const updatedInfo = chart.toBuilder(univerAPI.Enum.ChartTypeString.Line).setSubtitle('FY 2026').build()

await chart.update(updatedInfo)
const svg = await chart.exportImage({ format: 'svg' })
```

`exportImage()` returns `undefined` when the current host has no UI renderer. Call `await chart.remove()` only when you want to delete the inserted chart.

Register shared themes on `univerAPI`:

```typescript
registerTheme(name: string, theme: IEchartTheme): void
```

## Live data sources

`FChart.setDataSource()` replaces the host source without changing chart configuration. Sheet charts accept a range string. Slide, Board, and Document charts accept inline tables or resource references to a Sheet range or a complete Base table.

```typescript
await sheetChart.setDataSource('A1:C12')

await slideChart.setDataSource([
  ['Quarter', 'Revenue'],
  ['Q1', 120],
  ['Q2', 180],
])

await boardChart.setDataSource({
  unit: { selector: 'base-unit-id', type: 'base' },
  part: {
    kind: 'table',
    tableId: 'tasks-table-id',
    tableName: 'Tasks',
  },
})
```

Referenced Sheet sources use a `range` part with the sheet identity and A1 range. Referenced Base sources currently select a complete table.

## Detached builders

| API                    | Methods                                                                                                                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Builder lifecycle      | `setSource`, `setAbsolutePosition`, `setSize`, `build`                                                                                                                                                |
| Titles and legend      | `setTitle`, `clearTitle`, `setSubtitle`, `clearSubtitle`, `setLegend`, `clearLegend`                                                                                                                  |
| Appearance and data    | `setTheme`, `setPalette`, `setAppearance`, `setAggregation`, `setCategoryField`, `setCategoryFields`, `setMultiLevelCategoryAxis`, `setValueFields`, `setInvalidValueStrategy`, `setAutoGradientFill` |
| Type-specific builders | Axis, series, line, pie, bubble, candlestick, histogram, hierarchy, gauge, and relation-chart methods                                                                                                 |

Builder methods only change a detached draft. `build()` returns an insertable information snapshot.

## Multi-level category axes

When adjacent source fields form a hierarchy, pass their zero-based indexes to `setCategoryFields()` in root-to-leaf order, then enable the multi-level axis.

```ts
const info = worksheet
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    range: 'A1:D7',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
  })
  .setCategoryFields([0, 1])
  .setMultiLevelCategoryAxis(true)
  .setValueFields([2, 3])
  .setPosition('F2')
  .build()

const chart = await worksheet.insertChart(info)
chart.setCategoryFields([0, 1]).setMultiLevelCategoryAxis(true)
```

`clearCategoryFields()` removes the ordered category mapping. `setMultiLevelCategoryAxis(false)` only switches the hierarchical rendering off and preserves the selected fields.

## Live charts

| API                  | Methods                                                                                                                                                      |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Live inspection      | `getId`, `getType`, `getInfo`, `toBuilder`                                                                                                                   |
| Immediate updates    | `setType`, `setCategoryFields`, `clearCategoryFields`, `setMultiLevelCategoryAxis`, the other shared configuration setters, `setAbsolutePosition`, `setSize` |
| Asynchronous updates | `setDataSource`, `update`, `remove`                                                                                                                          |
| Order                | `setZOrder`, `bringToFront`, `bringForward`, `sendBackward`, `sendToBack`                                                                                    |
| Image export         | `exportImage(options?)` for a PNG or SVG data URL; requires `@univerjs-pro/chart-ui/facade`                                                                  |

## Host-specific builders

| Host   | Source and placement                                                                                |
| ------ | --------------------------------------------------------------------------------------------------- |
| Sheets | A1 ranges or range specs; `setPosition(anchor)`                                                     |
| Slides | Inline values or a Sheet resource reference; `setPlaceholder`, `setStroke`, `setZOrder`             |
| Boards | Inline values or a Sheet resource reference; `setContainer`, `setLane`, `setZOrder`                 |
| Docs   | Inline values or a Sheet resource reference; `setPosition`, `setLayout`, `setInline`, `setFloating` |

Slides, Boards, and Docs can reference a Sheet range instead of copying values:

```ts
const info = slide
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    unit: { selector: 'sales-workbook', type: 'sheet' },
    part: {
      kind: 'range',
      sheetName: 'Data',
      range: 'A1:B20',
      ref: 'Data!A1:B20',
    },
  })
  .setAbsolutePosition(120, 80)
  .setSize(640, 360)
  .build()

const chart = await slide.insertChart(info)
```

Source: `@univerjs-pro/engine-chart`, `@univerjs-pro/sheets-chart`, `@univerjs-pro/slides-chart`,
`@univerjs-pro/boards-chart`, `@univerjs-pro/docs-chart`, `@univerjs-pro/chart-ui`