---
title: "Size and view"
description: "A chart or a diagram fills its column at 16:9 until it gets a size of its own."
canonical_url: "https://tiptap.dev/docs/diagrams/guides/size-and-view"
---

# Size and view

A chart or a diagram fills its column at 16:9 until it gets a size of its own.

## Quick start

```ts
// Half the column, 4:3, stored in the document
editor.commands.setDiagramSize({ size: { width: 0.5, ratio: 4 / 3, locked: true } })

// 150 % in this view only
editor.storage.diagrams.setZoom({}, 1.5)
```

## What is stored and what is not

| Setting   | Stored in the document | Shared with collaborators | After a reload |
| --------- | ---------------------- | ------------------------- | -------------- |
| Size      | Yes                    | Yes                       | Kept           |
| Alignment | Yes                    | Yes                       | Kept           |
| Zoom      | No                     | No                        | Gone           |
| Pan       | No                     | No                        | Gone           |
| Maximize  | No                     | No                        | Gone           |

## Narrow screens

For phones, the [`chart.minRenderWidth`](https://tiptap.dev/docs/diagrams/api-reference/options.md#minrenderwidth) option draws a chart as wide
as on a large screen and shows it smaller. Compare a narrow chart with and without it:

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

## View functions

These are on `editor.storage.diagrams`. `target` is `{ pos? }`; without `pos`, the selected chart
or diagram.

| Function                          | Does                                                       |
| --------------------------------- | ---------------------------------------------------------- |
| `setZoom(target, zoom)`           | Sets the zoom. `zoom` is `number \| 'fit'`                 |
| `getZoom(target?)`                | Returns the zoom, or `null`                                |
| `setPan(target, { x, y })`        | Moves the zoomed picture inside its frame                  |
| `getPan(target?)`                 | Returns the offset, or `null`                              |
| `setMaximized(target, maximized)` | Lays the chart or diagram over the window, or puts it back |
| `getShownSize(target?)`           | Returns the size it shows on screen, or `null`             |

## Zoom

```ts
editor.storage.diagrams.setZoom({ pos }, 1.5) // 150 % of the size that fills the width
editor.storage.diagrams.setZoom({}, 'fit') // the selected chart, back to its width
```

- **A number** is a factor between `0.25` and `4` of the size at which the chart fills its width.
- **`'fit'`** is exactly that size.
- **Zoomed in**, the chart keeps its height and scrolls inside it.
- **Zoomed out**, it takes less room.
- **The picture is scaled**, not drawn again, so zoom works with every Renderer.
- **The chart's root** carries the zoom as `data-tt-chart-zoom`.

## Pan

```ts
editor.storage.diagrams.setZoom({ pos }, 2)
editor.storage.diagrams.setPan({ pos }, { x: 120, y: 40 })
```

Zoomed in, the picture is larger than its frame.

- **Dragging** the picture with the mouse held down moves it inside the frame.
- **`setPan`** does the same from code. `x` and `y` are how many pixels of the zoomed picture
  are moved out of view at the left and the top.
- **A press that does not move** selects the chart or diagram.
- **`'fit'`** moves the picture back to `0, 0`.
- **While the picture is dragged**, the root carries `data-tt-chart-panning` or
  `data-tt-flow-diagram-panning`.

## Maximize

```ts
editor.storage.diagrams.setMaximized({ pos }, true) // over the window
editor.storage.diagrams.setMaximized({ pos }, false) // back into the text
```

A maximized chart covers the window, or the area `--tt-chart-maximized-inset` leaves, and is
drawn again at that size. Its zoom starts at `'fit'`.

- **Maximizing another chart** puts the first back. At most one chart is maximized.
- **Escape** in the editor puts it back.
- **Deleting or moving the chart** puts it back.
- **While maximized**, the chart's root carries `data-tt-chart-maximized`.
- **Each change** dispatches a Transaction that leaves the document as it is, so a toolbar
  listening to `transaction` can update its button.

## Commands

### setDiagramSize

Gives the selected chart or diagram, or the one at `pos`, a size.

```ts
editor.commands.setDiagramSize({ size: { width: 0.5, ratio: 4 / 3, locked: true } })
```

| Option | Type                 | Description                                                                  |
| ------ | -------------------- | ---------------------------------------------------------------------------- |
| `size` | `FigureSize \| null` | The size, see below. `null` goes back to the full width at the natural shape |
| `pos`  | `number`             | The position of the chart or diagram. Defaults to the selected one           |

A `FigureSize` has these fields. Values outside the range are clamped.

| Field    | Type                            | Description                                                                                                            |
| -------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `width`  | `number`                        | A share of the column, from `0.1` to `1`                                                                               |
| `ratio`  | `number`                        | Width divided by height of the drawing area, from `0.25` to `8`                                                        |
| `locked` | `boolean`                       | A corner handle keeps the ratio                                                                                        |
| `align`  | `'left' \| 'center' \| 'right'` | The place, see [`setDiagramAlign`](https://tiptap.dev/docs/diagrams/guides/size-and-view.md#setdiagramalign). Optional |

Because the width is a share, the same document fits a narrow and a wide page.

| Where           | The size                                                        |
| --------------- | --------------------------------------------------------------- |
| A chart         | Is kept in its Chart Spec as `size`                             |
| A diagram       | Is kept in its `options` as `size`                              |
| An image export | Keeps the shape, at the export's usual width                    |
| Word            | Places the chart or the picture at that share of the page width |
| HTML            | Becomes `style="width: …%"` on the figure                       |

Returns `false` for anything that is not a size.

### setDiagramAlign

Places the selected chart or diagram, or the one at `pos`, at the `'left'`, in the `'center'`
or at the `'right'` of its column.

```ts
editor.commands.setDiagramAlign({ align: 'right' })
```

| Option  | Type                            | Description                                                        |
| ------- | ------------------------------- | ------------------------------------------------------------------ |
| `align` | `'left' \| 'center' \| 'right'` | The place                                                          |
| `pos`   | `number`                        | The position of the chart or diagram. Defaults to the selected one |

- **Stored** in the size as `align`. `center` is the default and is not written.
- **A figure without a size of its own** gets the size it shows on screen, `getShownSize()`,
  together with the alignment.
- **At the full width**, the alignment shows once the figure is made narrower.
- **A side handle** of a figure at the left or right grows it toward the other side only.
- **HTML** carries the place as margins.
- **Word** carries it as the alignment of the paragraph the figure stands in.

Returns `false` for a figure without a size that is not on screen, since its shape is not known.