Tiptap Docs

Size and view

A chart or a diagram fills its column at 16:9 until it gets a size of its own. Zoom, pan and maximize change only how one editor shows it.
Pro ExtensionAlphaPilot program
New tab

Quick start 

// 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

SettingStored in the documentShared with collaboratorsAfter a reload
SizeYesYesKept
AlignmentYesYesKept
ZoomNoNoGone
PanNoNoGone
MaximizeNoNoGone

Narrow screens

For phones, the chart.minRenderWidth option draws a chart as wide as on a large screen and shows it smaller. Compare a narrow chart with and without it:

New tab

View functions

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

FunctionDoes
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 

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 

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 

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.

editor.commands.setDiagramSize({ size: { width: 0.5, ratio: 4 / 3, locked: true } })
OptionTypeDescription
sizeFigureSize | nullThe size, see below. null goes back to the full width at the natural shape
posnumberThe position of the chart or diagram. Defaults to the selected one

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

FieldTypeDescription
widthnumberA share of the column, from 0.1 to 1
rationumberWidth divided by height of the drawing area, from 0.25 to 8
lockedbooleanA corner handle keeps the ratio
align'left' | 'center' | 'right'The place, see setDiagramAlign. Optional

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

WhereThe size
A chartIs kept in its Chart Spec as size
A diagramIs kept in its options as size
An image exportKeeps the shape, at the export's usual width
WordPlaces the chart or the picture at that share of the page width
HTMLBecomes 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.

editor.commands.setDiagramAlign({ align: 'right' })
OptionTypeDescription
align'left' | 'center' | 'right'The place
posnumberThe 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.

PreviouslyTools for a model