---
title: "Appearance"
description: "The Chart Spec holds a chart's settings, such as its title, legend, colors and frame."
canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/appearance"
---

# Appearance

The Chart Spec holds a chart's settings, such as its title, legend, colors and frame.

## Quick start

```ts
editor.commands.updateChartSpec({ spec: { title: 'Revenue', border: true, caption: true } })
```

## Chart Spec fields

| Field         | Type                          | Description                                                                                                                                                                          |
| ------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `title`       | `string`                      | Written above the chart                                                                                                                                                              |
| `description` | `string`                      | Alt text and accessible description                                                                                                                                                  |
| `caption`     | `boolean`                     | `true` shows the description as a visible caption below the chart                                                                                                                    |
| `legend`      | `ChartLegend`                 | `{ show, position }`. `show` is a `boolean`, `position` is `'top'`, `'right'`, `'bottom'` or `'left'`. Without it, the legend shows at the bottom                                    |
| `palette`     | `string[]`                    | The series colors of this chart, as CSS colors. Without it, the style's colors, then `--tt-chart-series-1` and the following custom properties                                       |
| `background`  | `string`                      | A solid CSS color behind the chart, such as a hex, `rgb()`, `hsl()` or named color. Without it, `--tt-chart-background`                                                              |
| `border`      | `boolean`                     | `true` frames the chart in `--tt-chart-border-color`                                                                                                                                 |
| `style`       | `string`                      | A registered style by id, such as `'ocean'`. See [Styles](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/styling.md#styles)                                                    |
| `stacked`     | `boolean`                     | `true` draws bars and areas on top of each other instead of side by side                                                                                                             |
| `innerRadius` | `number`                      | The hole of a doughnut, from `0` to `0.9` of the radius. Default `0.55`                                                                                                              |
| `orientation` | `'vertical' \| 'horizontal'`  | `'horizontal'` lays the bars on their side. See [Horizontal bars](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/appearance.md#horizontal-bars)                                |
| `series`      | `Record<string, SeriesStyle>` | Line styles of a line or area chart, by column id. See [Series line styles](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/appearance.md#series-line-styles)                   |
| `encoding`    | `ChartEncoding`               | `{ label?, series?, seriesIn? }`: which columns are drawn. See [Which columns are drawn](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/appearance.md#which-columns-are-drawn) |
| `size`        | `FigureSize`                  | `{ width, ratio, locked }`, see [`setDiagramSize`](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/size-and-view.md#setdiagramsize)                                             |
| `hidden`      | `boolean`                     | `true` while only the table the chart follows is shown. `setChartLayout` sets it. It is dropped when that table is gone                                                              |

`type` and `range`, the scale of a gauge, are on [Charts](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/overview.md#chart-types). `axes` is on
[Axes](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/axes.md), `references` on [Reference lines and bands](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/references.md). `renderer` holds
options that only one Renderer understands, see
[When the Renderer changes](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/overview.md#when-the-renderer-changes).

- `palette`, `background` and `border` override the `style`.
- An unknown `style` id is ignored.
- A `legend` without `show` is shown. A `legend` without a valid `position` stands at the bottom.
- A color in `palette` or `background` that is not a safe CSS color is dropped. A value that
  could load a resource, such as `url()`, is never a color.

## Horizontal bars

`spec.orientation: 'horizontal'` lays the bars of a bar or combo chart on their side, with the
categories down the left. Without it, or with `'vertical'`, bars stand upright.

```ts
editor.commands.updateChartSpec({ spec: { orientation: 'horizontal' } })
```

Not every Renderer lays bars on their side. See the chart types of
[ECharts](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/echarts.md#chart-types) and [D3](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/d3.md#chart-types),
and the [limits of Mermaid](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/mermaid.md#limits).

Other chart types ignore `orientation`, so it can stay in the spec when you change the type. Long
category names read better on bars that lie on their side than on labels turned at an angle.

## Series line styles

Give each line its own stroke, width, markers and curve:

> **Interactive demo:** [DiagramsSeriesStyles](https://embed-pro.tiptap.dev/preview/Extensions/DiagramsSeriesStyles)

`spec.series` sets how each series of a line or area chart is drawn, by column id:
`{ [columnId]: { line?, width?, marker?, smooth? } }`. A column without an entry keeps the
Renderer's default.

```ts
editor.commands.updateChartSpec({
  spec: { series: { forecast: { line: 'dashed', marker: 'none' } } },
})
```

| Field    | Values                                              |
| -------- | --------------------------------------------------- |
| `line`   | `'solid'`, `'dashed'` or `'dotted'`                 |
| `width`  | The stroke width in CSS pixels, 0.5 to 8. Default 2 |
| `marker` | `'none'`, `'circle'` or `'square'` at each value    |
| `smooth` | `true` draws a curve through the values             |

`updateChartSpec` replaces `series` as a whole. Pass every entry you want to keep.

The [ECharts](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/echarts.md#chart-types) and
[D3](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/d3.md#chart-types) Renderers draw every field. The Mermaid Renderer
declines a line chart with `series`, see its [limits](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/mermaid.md#limits).
Word draws all four on a line chart, and none on the edges of an area chart.

## Which columns are drawn

`encoding` names the columns a chart draws, by their id. The Chart Data keeps every column. See
[Which columns are drawn](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/overview.md#which-columns-are-drawn).

## Where the frame shows

The background reaches every Renderer and every export. The border and the caption appear in the
editor, in HTML and in a Word document. An SVG or image export frames the chart with the same
padding, border and caption as the editor.

## Choosing the Renderer

A chart is drawn by one of the registered Renderers. You can name one with `setChartRenderer`.
Otherwise the extension picks one, see
[Which Renderer draws a chart](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/overview.md#which-renderer-draws-a-chart). Changing the
Renderer changes only the drawing, never the Chart Data or the Chart Spec.

## Commands

### updateChartSpec

Changes fields of the Chart Spec and keeps the rest. A field set to `undefined` is removed.

```ts
editor.commands.updateChartSpec({ spec: { title: 'Revenue', stacked: undefined } })
```

| Option | Type             | Description                                          |
| ------ | ---------------- | ---------------------------------------------------- |
| `spec` | `ChartSpecPatch` | The fields to change                                 |
| `pos`  | `number`         | The chart's position. Defaults to the selected chart |

A field that is not valid, such as a color that is not one, is dropped. Returns `false` when
there is no chart at `pos`, or no chart is selected.

### setChartRenderer

Sets the Renderer that draws the chart. `null` goes back to the default.

```ts
editor.commands.setChartRenderer({ renderer: 'd3' })
```

| Option     | Type             | Description                                          |
| ---------- | ---------------- | ---------------------------------------------------- |
| `renderer` | `string \| null` | The id of a registered Renderer, or `null`           |
| `pos`      | `number`         | The chart's position. Defaults to the selected chart |

Returns `false` when there is no chart at `pos`, or no chart is selected.