--- title: "Size and view" description: "A chart or a diagram takes the full width of the editor's text until you give it a size of its own." canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/size-and-view" --- # Size and view A chart or a diagram takes the full width of the editor's text until you give it a size of its own. ## Quick start ```ts // Half the width of the editor's text, at 4:3, stored in the document editor.commands.setDiagramSize({ size: { width: 0.5, ratio: 4 / 3, locked: true } }) // 150 % in this editor only editor.storage.diagrams.setZoom({}, 1.5) ``` ## What is stored and what is not The document stores the size and the alignment. So collaborators share them, and they are kept after a reload. Zoom, pan and maximize change only how one editor shows a chart or a diagram. They are not shared, and they are gone after a reload. ## Narrow screens On phones, the [`chart.minRenderWidth`](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#minrenderwidth) option draws a chart as wide as on a large screen and then scales it down. Compare a narrow chart with and without the option: > **Interactive demo:** [DiagramsNarrowScreens](https://embed-pro.tiptap.dev/preview/Extensions/DiagramsNarrowScreens) ## View functions The view functions are on `editor.storage.diagrams`. Each takes a `target`, which is `{ pos? }`. Without `pos`, a function acts on the selected chart or diagram. | Function | What it 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 chart or diagram inside its frame | | `getPan(target?)` | Returns the offset `{ x, y }`, or `null` | | `setMaximized(target, maximized)` | Lays the chart or diagram over the window, or puts it back | | `getMaximized()` | Returns the position of the maximized chart or diagram, or `null` | | `getShownSize(target?)` | Returns the size it has on screen as a `FigureSize`, or `null` | These functions work only on a chart or a diagram that is on screen. For one that is not, the `set` functions return `false` and the `get` functions return `null`. ## Zoom ```ts editor.storage.diagrams.setZoom({ pos }, 1.5) // 150 % of the unzoomed size editor.storage.diagrams.setZoom({}, 'fit') // the selected chart, back to the unzoomed size ``` The unzoomed size, `'fit'`, is the size at which a chart fills its own width. A number is a factor of it, from `0.25` to `4`. A number outside that range is clamped. Zoomed in, the chart keeps its height, and you scroll inside it. Zoomed out, it takes less room. Every Renderer works with zoom, because the drawn chart is scaled, not drawn again. The chart's root element 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 }) ``` Pan moves a zoomed-in chart or diagram inside its frame. - **Dragging** with the mouse button held down moves it. A click without movement selects it. - **`setPan`** moves it from code. `x` and `y` are how many pixels of the zoomed chart or diagram are moved out of view at the left and at the top. - **`'fit'`** moves it back to `0, 0`. - **While you drag**, the root element 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, at the distance `--tt-chart-maximized-inset` from its edges. The chart is drawn again at the new size, and its zoom starts at `'fit'`. While maximized, its root element carries `data-tt-chart-maximized`. Only one chart can be maximized. Maximizing another chart, pressing Escape in the editor, or deleting or moving the chart puts it back. Each change dispatches a transaction that does not change the document, so a toolbar that listens to `transaction` can update its button. ## Resize handles With the [`resizable`](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#resizable) option, a selected chart or diagram shows handles while the editor is editable. The handles sit at the left and right sides, at the bottom, and at the two lower corners. - **A side handle** changes the width and keeps the height. A centered chart or diagram grows on both sides. One aligned left or right (see [`setDiagramAlign`](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/size-and-view.md#setdiagramalign)) grows only on the side of the handle. - **The bottom handle** changes the height. - **A corner handle** changes both. It keeps the aspect ratio while the size has `locked: true`. Holding Shift does the opposite. - **Near the full width**, a drag snaps to the edge of the editor's text. A double click on a handle sets the full width. - **When the drag ends**, `setDiagramSize` writes the size, as one undo step. ## 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 and the natural aspect ratio | | `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 width of the editor's text, from `0.1` to `1` | | `ratio` | `number` | The aspect ratio: width divided by height of the drawing area, from `0.25` to `8` | | `locked` | `boolean` | Whether a corner handle keeps the aspect ratio | | `align` | `'left' \| 'center' \| 'right'` | The alignment, see [`setDiagramAlign`](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/size-and-view.md#setdiagramalign). Optional | | Where | What happens to 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 aspect ratio, at the export's usual width | | Word | Places the chart or the diagram at that share of the page width | | HTML | Becomes `style="width: …%"` on the `
` element | Returns `false` when there is no chart or diagram, or when `size` is not a size. ### setDiagramAlign Aligns the selected chart or diagram, or the one at `pos`, to the `'left'`, the `'center'` or the `'right'` of the editor's text. ```ts editor.commands.setDiagramAlign({ align: 'right' }) ``` | Option | Type | Description | | ------- | ------------------------------- | ------------------------------------------------------------------ | | `align` | `'left' \| 'center' \| 'right'` | The alignment | | `pos` | `number` | The position of the chart or diagram. Defaults to the selected one | - **The alignment is stored** in the size as `align`. `center` is the default and is not written. - **A chart or diagram without a size of its own** gets the size it has on screen, `getShownSize()`, together with the alignment. - **At the full width**, you see the alignment only once the chart or diagram is made narrower. - **HTML** carries the alignment as margins. **Word** carries it as the alignment of the paragraph that holds the chart or diagram. Returns `false` when there is no chart or diagram, or for an unknown alignment. It also returns `false` for a chart or diagram that has no size of its own and is not on screen, because the command reads the aspect ratio from the screen.