--- title: "Appearance" description: "How a chart is framed and colored, and which Renderer draws it." canonical_url: "https://tiptap.dev/docs/diagrams/charts/appearance" --- # Appearance How a chart is framed and colored, and which Renderer draws it. ## Quick start ```ts editor.commands.updateChartSpec({ spec: { title: 'Revenue', border: true, caption: true } }) ``` ## Framing fields Besides type, title, legend, palette and axes, the spec holds how the chart is framed: | Field | Type | Description | | ------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `description` | `string` | Alt text and accessible description | | `caption` | `boolean` | `true` shows the description as a visible caption below the chart | | `background` | `string` | A solid CSS color behind the chart: a hex, `rgb()`, `hsl()` or named color. Anything else is dropped | | `border` | `boolean` | `true` frames the chart in `--tt-chart-border-color` | | `hidden` | `boolean` | `true` while only the table the chart follows is shown. Set by `setChartLayout`, dropped when that table is gone | | `size` | `FigureSize` | `{ width, ratio, locked }`, see [`setDiagramSize`](https://tiptap.dev/docs/diagrams/guides/size-and-view.md#setdiagramsize) | | `series` | `Record` | Line styles of a line or area chart, by column id. See [Series line styles](https://tiptap.dev/docs/diagrams/charts/appearance.md#series-line-styles) | | `style` | `string` | A style by id, such as `'ocean'`; see [Styles](https://tiptap.dev/docs/diagrams/guides/styling.md#styles) | | `encoding` | `ChartEncoding` | `{ label?, series?, seriesIn? }`: which columns are drawn. See [Which columns are drawn](https://tiptap.dev/docs/diagrams/charts/appearance.md#which-columns-are-drawn) | - **`palette`, `background` and `border`** override the `style`. - **An unknown `style` id** is ignored. ### 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' } }) ``` | Renderer | Bar | Combo | | -------- | ---------------------------------------------- | -------------------- | | ECharts | On their side | On their side | | d3 | On their side | Upright | | Mermaid | Declined: another registered Renderer draws it | Not drawn by Mermaid | - **Other chart types** ignore it, so it may stay in the spec when the type changes. - **Long category names** read better on their side than 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 a series of a line or area chart is drawn: `{ [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. | Renderer | Draws | | -------- | ------------------------------------------------------------ | | ECharts | Every field | | d3 | Every field | | Word | All four on a line chart, none on the edges of an area chart | | Mermaid | None, so a line chart with `series` goes to another Renderer | ### Which columns are drawn `encoding` holds column ids: | Field | Description | | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | | `label` | The column that names the rows | | `series` | The columns drawn, in that order | | `seriesIn` | `'rows'` swaps rows and columns, see [`setChartSeriesIn`](https://tiptap.dev/docs/diagrams/data/overview.md#setchartseriesin) | - **Without `encoding`**, the first column is the label and every number column a series. - **The Chart Data keeps every column.** `encoding` only decides what is drawn, in the editor and in every export. - **An id that is not in the data** is ignored. - **A `series` that names no existing column** draws every series. ## Where the frame shows - **The background** reaches every Renderer and every export. - **The border and the caption** appear in the editor, in HTML, in a Word document and in an SVG or image export. - **An SVG or image export** frames the chart with the padding, border and caption the editor shows. ## Choosing the Renderer A chart is drawn by one of the [registered Renderers](https://tiptap.dev/docs/diagrams/renderers/overview.md), in this order: 1. The Renderer the chart names (`setChartRenderer`), if it is registered and draws the chart type. 2. Otherwise `defaultRenderer`, if it draws the type. 3. Otherwise the first registered Renderer that draws the type. ### When a Renderer declines a chart A Renderer can decline a chart of a type it draws, through `draws`. The [Mermaid Renderer](https://tiptap.dev/docs/diagrams/renderers/mermaid.md) declines a bar chart with several series and a line chart with line styles. - **Another Renderer draws the type:** the next one in the order above draws the chart. - **No other Renderer draws the type:** the declining Renderer draws it after all. - **The chart** keeps the Renderer it names. - **The chart's root** says in `data-tt-chart-renderer` which Renderer drew it. - **`export` with an explicit `renderer` option** uses that Renderer as it is. ### When no Renderer draws the type The chart shows what [`unavailable`](https://tiptap.dev/docs/diagrams/api-reference/options.md#unavailable) returns and keeps its data. ### When the Renderer changes - **The picture** changes. Data and spec stay as they are. - **Options a chart stores for one Renderer** under `spec.renderer[id]` are ignored by the others. - **Colors and fonts** come from the same `--tt-chart-*` custom properties for every Renderer, so charts look alike whichever library draws them. See [Styling](https://tiptap.dev/docs/diagrams/guides/styling.md). ## Commands ### updateChartSpec Changes fields of the Chart Spec. 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 | ### setChartRenderer Draws the chart with the Renderer of that id, or with the default for `null`. Data and spec are not touched. ```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 |