# Element
URL: https://polotno.com/docs/element



**Element** represents a graphical object on the page or inside a group. An element can have one of these types:

* **text**
* **image**
* **svg**
* **line**
* **figure**
* **video**
* **table**
* **group**

```ts
const element = store.activePage.addElement({
  type: 'text',
  x: 50,
  y: 50,
  fill: 'black',
  text: 'hello',
});

// logs 50
console.log(element.x);

// set new position
element.set({ x: 100 });
```

## Basic actions [#basic-actions]

### Read properties [#read-properties]

At any time, you can access any property of an element. See documentation for every element type to view all available properties.

```ts
const element = store.selectedElements[0];
// logs type of element
console.log(element.type);
// logs id of element
console.log(element.id);
```

### element.set(attrs) [#elementsetattrs]

Set new attributes to the element.

```ts
text.set({ x: text.x + 10, text: 'new text' });
```

### Custom properties [#custom-properties]

You can't write any arbitrary property directly on an element. If you want to store additional data, use the `custom` attribute.

```ts
// 🛑 this line will not work, because elements have no attribute `userId`
element.set({ userId: '12' });
// 🟢 you can write such data into "custom" attribute
element.set({ custom: { userId: '12' } });
// read custom attribute
console.log(element.custom?.userId);
```

### element.moveUp() [#elementmoveup]

Move element up on z-index.

```ts
text.moveUp();
```

### element.moveDown() [#elementmovedown]

Move element down on z-index.

```ts
text.moveDown();
```

### element.moveTop() [#elementmovetop]

Move element to the top of the page or a group.

```ts
text.moveTop();
```

### element.moveBottom() [#elementmovebottom]

Move element to the bottom of the page or a group.

```ts
text.moveBottom();
```

### Locking [#locking]

Use `draggable`, `contentEditable`, `styleEditable`, `removable` and `resizable` attributes to lock element editing.

```ts
// lock the object
element.set({
  // can element be moved and rotated
  draggable: false,
  // can we change content of element?
  contentEditable: false,
  // can we change style of element?
  styleEditable: false,
  // can we resize element?
  resizable: false,
  // can we remove an element?
  removable: false,
});

console.log(element.locked); // true

// unlock it
element.set({
  // can element be moved and rotated
  draggable: true,
  // can we change content of element?
  contentEditable: true,
  // can we change style of element?
  styleEditable: true,
  // can we resize element?
  resizable: true,
  removable: true,
});
```

See [Element Locking](/docs/element-locking) for comprehensive documentation on locking properties, use cases, and custom UI examples.

## Text element [#text-element]

Text elements allow you to create text on the canvas.

Here is the example of default properties:

```ts
page.addElement({
  type: 'text',
  x: 0,
  y: 0,
  rotation: 0,
  locked: false, // deprecated
  blurEnabled: false,
  blurRadius: 10,
  brightnessEnabled: false,
  brightness: 0,
  shadowEnabled: false,
  shadowBlur: 5,
  shadowOffsetX: 0,
  shadowOffsetY: 0,
  shadowColor: 'black',
  shadowOpacity: 1,
  name: '', // name of element, can be used to find element in the store
  text: 'Hey, polotno',
  // placeholder is working similar to input placeholder
  // it will be rendered (dimmed) if no text is defined
  // and we will use it in input element too
  // useful for template canvas, where users will need to replace text elements
  // important (!) placeholders are visible in export results too,
  // so remove or fill them before exporting
  placeholder: '',
  fontSize: 14,
  fontFamily: 'Roboto',
  fontStyle: 'normal', // can be normal or italic
  fontWeight: 'normal', // numeric weight as string too, e.g. '400', '700'; 'bold' works as alias
  textDecoration: '',
  fill: 'black',
  align: 'center',
  width: 0,
  strokeWidth: 0,
  stroke: 'black',
  lineHeight: 1,
  letterSpacing: 0, // % from font size,
  backgroundEnabled: false,
  backgroundColor: '#7ED321',
  backgroundOpacity: 1,
  backgroundCornerRadius: 0.5, // % from half line height
  backgroundPadding: 0.5, //% from half line height

  // can user select element?
  // if false, element will be "invisible" for user clicks
  selectable: true,
  // use for absolute positing of element
  alwaysOnTop: false,
  // also we can hide some elements from the export
  showInExport: true,
  // can element be moved and rotated
  draggable: true,
  // can we change content of element?
  contentEditable: true,
  // can we remove element from UI with button or keyboard?
  removable: true,
  // can we resize element?
  resizable: true,
  // can we change style of element?
  styleEditable: true,
});
```

### text.toggleEditMode() [#texttoggleeditmode]

Enable edit mode for the text. It puts the cursor inside the text and a user can do regular text editing. You can call `text.toggleEditMode()` programmatically (e.g. right after creating a new text element).

## Image element [#image-element]

Image element draws an image on the canvas. By default images do smart-cropping to fit into its size.

```ts
page.addElement({
  type: 'image',
  x: 0,
  y: 0,
  rotation: 0,
  locked: false, // deprecated
  blurEnabled: false,
  blurRadius: 10,
  brightnessEnabled: false,
  brightness: 0,
  shadowEnabled: false,
  shadowBlur: 5,
  shadowOffsetX: 0,
  shadowOffsetY: 0,
  shadowColor: 'black',
  shadowOpacity: 1,
  name: '', // name of element, can be used to find element in the store
  // url path to image
  src: 'https://example.com/image.png',
  keepRatio: false, // can we change aspect ratio of element on resize
  stretchEnabled: false, // can we stretch image on any axis

  // url path to svg or image that will be used to clip image
  // can be used for image framing
  clipSrc: '',
  width: 100,
  height: 100,
  cropX: 0, // 0-1 : % from original image width
  cropY: 0, // 0-1 : % from original image height
  cropWidth: 1, // 0-1 : % from original image width
  cropHeight: 1, // 0-1 : % from original image height
  cornerRadius: 0,
  borderColor: 'black',
  borderSize: 0,
  flipX: false,
  flipY: false,

  // can user select element?
  // if false, element will be "invisible" for user clicks
  selectable: true,
  // use for absolute positing of element
  alwaysOnTop: false,
  // also we can hide some elements from the export
  showInExport: true,
  // can element be moved and rotated
  draggable: true,
  // can we change content of element?
  contentEditable: true,

  // can we remove element from UI with button or keyboard?
  removable: true,
  // can we resize element?
  resizable: true,
});
```

### image.toggleCropMode() [#imagetogglecropmode]

Enter into "crop mode" of the image programmatically.

```tsx
<Button
  minimal
  icon={<Crop />}
  // use capture handler to handle click event sooner
  onClickCapture={(e) => {
    // stop propagation to prevent autohide of crop mode on current click
    e.stopPropagation();
    element.toggleCropMode(true);
  }}
/>
```

### Image filters [#image-filters]

Polotno recognizes two filter categories, each with its own API pattern.

1. Old filters (use `element.set`):

```txt
sepiaEnabled
grayscaleEnabled
blurEnabled, blurRadius
brightnessEnabled, brightness
```

2. Combined filters (use `element.setFilter`):

```txt
cold
natural
warm

temperature
contrast
shadows
white
black
saturation
vibrance
```

Examples:

```ts
// 1. Old filters
shape.set({ sepiaEnabled: true });
shape.set({ blurEnabled: true, blurRadius: 12 });
shape.set({ brightnessEnabled: true, brightness: 0.25 }); // +25 %

// 2. One‑active preset (replaces previous preset)
shape.setFilter('warm');

// 3. Combined numeric filters (stackable)
shape.setFilter('temperature', -0.2);
shape.setFilter('contrast', 0.15);
shape.setFilter('vibrance', 0.3);

// disabling:
// Old filters off
shape.set({
  sepiaEnabled: false,
  blurEnabled: false,
  brightnessEnabled: false,
});

// Remove current preset
shape.setFilter('warm', null);

// Clear all combined filters
['temperature', 'contrast', 'shadows', 'white', 'black', 'saturation', 'vibrance']
  .forEach((f) => shape.setFilter(f, null));
```

## SVG element [#svg-element]

SVG elements work similarly to Image elements but can replace internal colors.

```ts
const svgElement = page.addElement({
  type: 'svg',
  src: 'https://example.com/image.svg',
  maskSrc: '', // should we draw mask image over svg element?
  keepRatio: false, // can we change aspect ratio of svg?
  stretchEnabled: false, // can we stretch image on any axis
  x: 0,
  y: 0,
  rotation: 0,
  locked: false, // deprecated
  blurEnabled: false,
  blurRadius: 10,
  brightnessEnabled: false,
  brightness: 0,
  shadowEnabled: false,
  shadowBlur: 5,
  shadowOffsetX: 0,
  shadowOffsetY: 0,
  shadowColor: 'black',
  shadowOpacity: 1,
  name: '', // name of element, can be used to find element in the store
  width: 100,
  height: 100,
  flipX: false,
  flipY: false,
  cornerRadius: 0,
  // can user select element?
  // if false, element will be "invisible" for user clicks
  selectable: true,
  // use for absolute positing of element
  alwaysOnTop: false,
  // also we can hide some elements from the export
  showInExport: true,
  // can element be moved and rotated
  draggable: true,
  // can we change content of element?
  contentEditable: true,
  // can we remove element from UI with button or keyboard?
  removable: true,
  // can we resize element?
  resizable: true,
  // map of originalColor -> newColor, used to replace colors in svg image
  // do not change it manually. Instead use `el.replaceColor(originalColor, newColor)`
  colorsReplace: {},
});
```

If you want to detect colors in an SVG string you can use this:

```ts
import { urlToString, getColors, useSvgColors } from 'polotno/utils/svg';

// in react component:
const Toolbar = ({ element }) => {
  const colors = useSvgColors(element.src); // will return array of colors detected in the svg image
};

// in functions:
async function getSvgColors(element) {
  const svgString = await urlToString(element.src);
  const colors = getColors(svgString);
}
```

### svgElement.replaceColor(oldColor, newColor) [#svgelementreplacecoloroldcolor-newcolor]

Some SVG files support color replacement when a color is defined as `fill` on internal nodes. You can replace specific colors to modify the original image.

```ts
svgElement.replaceColor('red', 'blue');
```

In the editor, multi-color SVGs open a color palette popover listing every detected color, with **Recolor all** to tint them at once. Each `replaceColor` call adds an entry to the element's `colorsReplace` map.

### svgElement.resetColors() [#svgelementresetcolors]

Revert all color replacements, restoring the SVG's original colors (clears the `colorsReplace` map). This backs the **Reset** action in the SVG color popover.

```ts
svgElement.resetColors();
```

## Line element [#line-element]

Use line elements to draw lines and arrows on the canvas. For now, line elements may not support all available filters from JSON.

```ts
const lineElement = page.addElement({
  type: 'line',
  x: 0,
  y: 0,
  width: 400,
  height: 10,
  name: '', // name of element, can be used to find element in the store
  color: 'black',
  rotation: 0,
  dash: [], // array of numbers, like [5, 5]
  startHead: '', // can be empty, arrow, triangle, circle, square, bar
  endHead: '', // can be empty, arrow, triangle, circle, square, bar
  // can user select element?
  // if false, element will be "invisible" for user clicks
  selectable: true,
  // use for absolute positing of element
  alwaysOnTop: false,
  // also we can hide some elements from the export
  showInExport: true,
  // can element be moved and rotated
  draggable: true,
  // can we change content of element?
  contentEditable: true,
  // can we remove element from UI with button or keyboard?
  removable: true,
  // can we resize element?
  resizable: true,
  styleEditable: true,
});
```

## Figure element [#figure-element]

Use figure to draw basic shapes on the canvas. It has a large collection of shapes controlled by `subType`.

```ts
const figureElement = page.addElement({
  type: 'figure',
  subType: 'rect',
  x: 0,
  y: 0,
  width: 400,
  height: 400,
  fill: 'black',
  stroke: 'red',
  strokeWidth: 40,
  cornerRadius: 40,
});
```

Currently supported list of `subType`:

**rect**, **circle**, **star**, **triangle**, **rightTriangle**, **diamond**, **pentagon**, **hexagon**, **speechBubble**, **cross**, **arc**, **cloud**, **rightArrow**, **leftArrow**, **downArrow**, **upArrow**, **asterisk1**, **asterisk2**, **bookmark**, **butterfly**, **cylinder**, **diamond2**, **door**, **drop1**, **drop2**, **explosion**, **flag**, **flower**, **frame**, **heart1**, **home**, **home2**, **hourglass**, **house**, **keyhole**, **kiss**, **leaf**, **lightning1**, **lightning2**, **magnet**, **mithosis**, **orangeRicky**, **party**, **pillow**, **polygon**, **rainbow**, **rhodeIsland**, **shell**, **shield1**, **shield2**, **skewedRectangle**, **softFlower**, **softStar**, **stairs1**, **stairs2**, **teewee**, **blob1**, **blob10**, **blob11**, **blob12**, **blob13**, **blob14**, **blob15**, **blob16**, **blob17**, **blob18**, **blob19**, **blob2**, **blob20**, **blob21**, **blob22**, **blob23**, **blob24**, **blob25**, **blob26**, **blob27**, **blob28**, **blob29**, **blob3**, **blob30**, **blob31**, **blob32**, **blob4**, **blob5**, **blob6**, **blob7**, **blob8**, **blob9**

## Video element [#video-element]

Use video to render a video on the canvas. Video element has many properties similar to the image element.

```ts
const videoElement = page.addElement({
  type: 'video',
  x: 0,
  y: 0,
  rotation: 0,

  // url path to video
  src: 'https://example.com/image.png',
  // start/end time of video in % from video duration
  // can be used for trimming video
  startTime: 0,
  endTime: 1,

  shadowEnabled: false,
  shadowBlur: 5,
  shadowOffsetX: 0,
  shadowOffsetY: 0,
  shadowColor: 'black',
  shadowOpacity: 1,
  name: '', // name of element, can be used to find element in the store

  width: 100,
  height: 100,
  cropX: 0, // 0-1 : % from original image width
  cropY: 0, // 0-1 : % from original image height
  cropWidth: 1, // 0-1 : % from original image width
  cropHeight: 1, // 0-1 : % from original image height
  borderColor: 'black',
  borderSize: 0,
  flipX: false,
  flipY: false,

  // can user select element?
  // if false, element will be "invisible" for user clicks
  selectable: true,
  // use for absolute positing of element
  alwaysOnTop: false,
  // also we can hide some elements from the export
  showInExport: true,
  // can element be moved and rotated
  draggable: true,
  // can we change content of element?
  contentEditable: true,

  // can we remove element from UI with button or keyboard?
  removable: true,
  // can we resize element?
  resizable: true,
});
```

## Group element [#group-element]

Group element is a container for other elements. It can be used to move multiple elements together.

Here is the example of default properties and usage:

```ts
const page = store.addPage();
page.addElement({
  type: 'text',
  text: 'Hello world',
  id: 'text-1',
});
page.addElement({
  type: 'text',
  text: 'Hello world',
  id: 'text-2',
});
const group = store.groupElements(['text-1', 'text-2']);

group.set({
  name: 'group',
  opacity: 0.5,

  custom: {},

  visible: true,
  selectable: true,
  removable: true,
  alwaysOnTop: false,
  showInExport: true,
});

// ungroup:
store.ungroupElements([group.id]);
```

## Table element [#table-element]

A table element renders a grid of editable text cells on the canvas. Tables support configurable rows and columns, per-cell text styling, cell merging, per-side border customization, keyboard navigation, and auto-growing rows that expand to fit content.

Tables do **not** support shadow, blur, brightness, sepia, grayscale, or filter effects.

```ts
const table = page.addElement({
  type: 'table',
  x: 50,
  y: 50,
  width: 400,
  height: 250,
  rows: 3,
  cols: 4,

  // text styling defaults (inherited by all cells)
  fontSize: 30,
  fontFamily: 'Roboto',
  fontWeight: 'normal',
  fontStyle: 'normal',
  textDecoration: '',
  textTransform: 'none',
  fill: 'black',
  align: 'left',
  verticalAlign: 'top',
  lineHeight: 1.2,
  letterSpacing: 0,
  strokeWidth: 0,
  stroke: 'black',

  // border defaults
  borderColor: '#000000',
  borderWidth: 1,
  borderStyle: 'solid', // 'solid', 'dashed', 'dotted', 'none'

  // cell defaults
  cellBackground: 'transparent',
  cellPadding: 4,

  name: '',
  selectable: true,
  alwaysOnTop: false,
  showInExport: true,
  draggable: true,
  contentEditable: true,
  removable: true,
  resizable: true,
  styleEditable: true,
});
```

Cells, `colWidths`, and `rowHeights` are generated automatically when omitted. Each column and row starts with equal width/height.

### Pre-populating cells [#pre-populating-cells]

You can pass cell data when creating a table. Cells are stored in **row-major order** (left-to-right, top-to-bottom). Only properties that differ from the table defaults need to be specified.

```ts
page.addElement({
  type: 'table',
  x: 50,
  y: 50,
  width: 400,
  height: 200,
  rows: 2,
  cols: 3,
  cells: [
    { id: 'h1', text: 'Name' },
    { id: 'h2', text: 'Role' },
    { id: 'h3', text: 'Email' },
    { id: 'r1', text: 'Alice' },
    { id: 'r2', text: 'Engineer' },
    { id: 'r3', text: 'alice@example.com' },
  ],
});
```

### Cell access [#cell-access]

```ts
// Get a specific cell by row/column index (0-based)
const cell = table.getCell(0, 2); // row 0, column 2

// All visible (non-merged) cells
const visible = table.visibleCells;

// Currently focused cells
const focused = table.focusedCells;

// Cell currently being edited (or undefined)
const editing = table.editingCell;
```

### Row operations [#row-operations]

```ts
// Add a row at index (pushes existing rows down)
table.addRow(1);

// Remove a row by index
table.removeRow(2);

// Resize a row border between row[index] and row[index+1]
// delta is a fraction of total height
table.resizeRow(0, 0.05);

// Make all rows the same height
table.distributeRowsEvenly();
```

### Column operations [#column-operations]

```ts
// Add a column at index (pushes existing columns right)
table.addColumn(2);

// Remove a column by index
table.removeColumn(0);

// Resize a column border between col[index] and col[index+1]
// delta is a fraction of total width
table.resizeColumn(1, -0.03);

// Make all columns the same width
table.distributeColumnsEvenly();
```

### Cell focus and editing [#cell-focus-and-editing]

```ts
// Focus a single cell
table.focusCell(cell.id);

// Add a cell to the current selection
table.focusCell(cell.id, true);

// Focus a rectangular range from the anchor cell to (row, col)
table.focusCellRange(2, 3);

// Clear all cell focus and exit editing
table.clearCellFocus();

// Enter text editing mode for a cell
table.enterCellEdit(cell.id);

// Exit text editing mode
table.exitCellEdit();
```

### Cell styling [#cell-styling]

Each cell can override any of the table's text styling defaults. When a property is `null` or `undefined`, the cell inherits the table-level value.

```ts
// Update cell properties
cell.set({
  text: 'Hello',
  fontSize: 24,
  fill: 'red',
  fontWeight: 'bold',
  cellBackground: '#f0f0f0',
});

// Reset a cell property to inherit from the table
cell.set({ fontSize: null });
```

### Borders [#borders]

Each cell has four border sides (`top`, `right`, `bottom`, `left`). Border properties follow a three-level resolution: cell override → table default → hardcoded fallback.

```ts
// Set borders on multiple cells at once
// Automatically syncs adjacent cells
table.setCellBorders(
  [cell1.id, cell2.id],
  ['top', 'bottom'],
  { color: 'red', width: 2, style: 'dashed' },
);

// Set a single border on one cell (does NOT sync adjacent cells)
cell.setBorder('top', { color: 'blue', width: 1 });

// Read the effective border for a side
const border = cell.getEffectiveBorder('top');
// => { color: string, width: number, style: string }
```

### table.clone() [#tableclone]

Clone a table (generates new IDs for the table and all cells, remaps `mergedInto` references).

```ts
const copy = table.clone({ x: table.x + 50 });
```


---

# Page
URL: https://polotno.com/docs/page



**Page** is a container for elements in the **store**. A **store** may have several pages.

```ts
const page = store.addPage({
  background: 'grey', // default is "white"
});
```

## page.set(attrs) [#pagesetattrs]

You can use `set()` to change properties of the page container. You can change `background`, `custom`, `bleed` (plus per-side `bleedTop`, `bleedRight`, `bleedBottom`, `bleedLeft` overrides), `width`, and `height`.

See also: [docs](/docs/page#pagesetattrs)

```ts
page.set({
  // background can be any CSS color string or a URL to an image
  background: 'red',
  // you can use "custom" to save your own app-specific data
  custom: { myInternalId: 'some-id-here' },
  bleed: 10, // in pixels
  bleedBottom: 20, // optional per-side override of "bleed"
  width: 1000, // in pixels. Use 'auto' to inherit width from the store
  height: 1000, // in pixels. Use 'auto' to inherit height from the store
});
```

## `page.setSize({ width, height, useMagic })` [#pagesetsize-width-height-usemagic-]

Change size of the specified page. If `useMagic` is `true`, all elements will be resized proportionally.

See also: [docs](/docs/page#pagesetsize-width-height-usemagic-)

```ts
page.setSize({
  width: 1000,
  height: 1000,
  useMagic: true,
});
```

## page.addElement(attrs) [#pageaddelementattrs]

Create an element with the specified attributes. It is important to provide the `type` attribute.

See also: [docs](/docs/page#pageaddelementattrs)

```ts
store.activePage?.addElement({
  type: 'text',
  x: 50,
  y: 50,
  fill: 'black',
  text: 'hello',
});
```

## page.clone() [#pageclone]

Duplicate the page.

See also: [docs](/docs/page#pageclone)

```ts
store.activePage?.clone();
```

## page.setZIndex(index) [#pagesetzindexindex]

Change the order of pages.

See also: [docs](/docs/page#pagesetzindexindex)

```ts
// move active page to the beginning of the list
store.activePage?.setZIndex(0);
```

## page.children [#pagechildren]

Use `children` to access elements inside the page.

See also: [docs](/docs/page#pagechildren)

```ts
// move every element by 10px to the right
store.activePage?.children.forEach((element) => {
  element.set({ x: element.x + 10 });
});
```

## page.computedWidth [#pagecomputedwidth]

Return width of the page in pixels.

See also: [docs](/docs/page#pagecomputedwidth)

## page.computedHeight [#pagecomputedheight]

Return height of the page in pixels.

See also: [docs](/docs/page#pagecomputedheight)


---

# Store
URL: https://polotno.com/docs/store



Store is a **root data model** object that you can use to read and control canvas content, check selection, export into different formats and a lot more! It will also provide you with access to [Pages](/docs/page) and [Elements](/docs/element).

```ts
import { createStore } from 'polotno/model/store';
const store = createStore({
  key: 'YOUR_API_KEY', // you can create it here: https://polotno.com/cabinet/
  // you can hide back-link on a paid license
  // but it will be good if you can keep it for Polotno project support
  showCredit: true,
});
```

## Working with pages [#working-with-pages]

### store.addPage() [#storeaddpage]

Store is a set of pages. Each page has elements on it.

```ts
const page = store.addPage();
```

### store.pages [#storepages]

Getter. Returns all pages of the store.

### store.activePage [#storeactivepage]

Getter. Returns current active (focused) page or the last created.

### store.selectPage(id) [#storeselectpageid]

Mark a page as active. It will automatically scroll `Workspace` to that page. You may think about this method as “focusPage”. For backward compatibility, we keep the original name for now.

```ts
// focus second page
store.selectPage(store.pages[1].id);
```

### store.selectedPages [#storeselectedpages]

Returns array of currently selected pages. A user may select a page by clicking on its background or from `PagesTimeline` component.

### store.selectPages(ids) [#storeselectpagesids]

Mark pages as selected for group actions in `PagesTimeline` or visibility of page background properties in the toolbar.

```ts
store.selectPages([store.activePage.id]); // show page props in the toolbar
store.selectPages([id1, id2]); // select several pages for highlight in the Timeline
```

### store.deletePages(ids) [#storedeletepagesids]

Remove pages from the store.

```ts
// remove current page
store.deletePages([store.activePage.id]);
```

### store.clear() [#storeclear]

Remove all pages from the store.

```ts
store.clear(); // it will remove all data and reset undo history

store.clear({ keepHistory: true }); // it will remove all data but keep undo history
```

## UI [#ui]

### store.width and store.height [#storewidth-and-storeheight]

Returns size of every page.

```ts
console.log('Width is', store.width);
```

### store.setSize(width, height, shouldUseMagicResize?) [#storesetsizewidth-height-shouldusemagicresize]

Set new size of every page in the store.

```ts
// just change the pages size
store.setSize(1000, 500);

// resize all pages and apply "magic resize"
// magic resize will automatically change sizes of all elements and adjust their position for a new size
store.setSize(1000, 500, true);
```

### store.scale [#storescale]

Getter for current zoom level of the active page.

```ts
console.log('zoom is', store.scale);
```

### store.setScale(size) [#storesetscalesize]

Change zooming of active page.

```ts
store.setScale(2);
```

### store.openedSidePanel [#storeopenedsidepanel]

Getter for current opened side panel.

### store.previousOpenedSidePanel [#storepreviousopenedsidepanel]

Name of the side-panel that was opened before the current one. Useful if you want to open a side panel temporarily for some action then restore the original side panel.

### store.openSidePanel(panelName) [#storeopensidepanelpanelname]

Change open side panel manually. The `panelName` corresponds to the `name` property of a section.

```ts
store.openSidePanel('templates');
```

In addition to the visible tab sections, Polotno has several built-in hidden panels: `effects`, `animation`, and `image-clip`. See [Hidden Panels](/docs/hidden-panels) for details.

**Note:** Calling `store.openSidePanel('')` before the `<SidePanel>` component mounts will not work, because the component resets the panel to its default on mount. To hide the side panel on initial load, use the `defaultSection=""` prop on the `<SidePanel>` component instead. See [Side Panel overview](/docs/side-panel-overview) for details.

### `store.setUnit({ unit, dpi })` [#storesetunit-unit-dpi-]

Set unit metrics to use in UI.

```ts
store.setUnit({
  unit: 'mm', // mm, cm, in, pt, px
  dpi: 300,
});
```

Important! Setting new unit will NOT change values in store and elements attributes, such as width, height, x, y, fontSize. They will still be saved in pixels. Unit metrics will be used only for default UI from Polotno.

### store.unit [#storeunit]

Returns unit used in UI to display measures. By default it is px. You can change it to pt, mm, cm, in.

### store.dpi [#storedpi]

Returns dpi used to convert pixels to other units.

### store.toggleBleed() [#storetogglebleed]

Show or hide bleed area on the workspace.

```ts
store.activePage.set({ bleed: 20 }); // set bleed in pixels

store.toggleBleed();
store.toggleBleed(false);
```

### store.bleedVisible [#storebleedvisible]

Getter for current state of bleed visibility.

### store.toggleRulers() [#storetogglerulers]

Show or hide rulers on workspace.

```ts
store.toggleRulers();
store.toggleRulers(false);
```

### store.rulersVisible [#storerulersvisible]

Getter for current state of rulers visibility.

### store.toggleDistanceGuides() [#storetoggledistanceguides]

Show or hide distance guides on the workspace. Distance guides appear when a user selects an element and holds `ALT`; this method forces them on even without the modifier key.

```ts
store.toggleDistanceGuides();
store.toggleDistanceGuides(false);
```

### store.distanceGuidesVisible [#storedistanceguidesvisible]

Getter for current state of distance guides visibility.

### store.setRole(role) [#storesetrolerole]

Set role of the current user. Possible values are: `user`, `admin`, and `viewer` (read-only). For more information see [Roles Documentation](/docs/user-roles).

```ts
store.setRole('admin');
```

## Tools [#tools]

### store.setTool(toolName) [#storesettooltoolname]

Switch between different canvas tools. Available values: `selection`, `draw`.

```ts
// enable drawing mode
store.setTool('draw');

// return to default selection mode
store.setTool('selection');
```

### store.tool [#storetool]

Getter for current active tool. Returns `selection` or `draw`.

```ts
console.log(store.tool); // 'selection'
```

### store.setToolOptions(options) [#storesettooloptionsoptions]

Configure options for the drawing tool. Sets stroke properties for freehand drawing.

```ts
store.setToolOptions({
  strokeWidth: 50,  // brush size in pixels
  stroke: 'red',    // stroke color (any CSS color)
  opacity: 0.4      // opacity from 0 to 1
});
```

### store.toolOptions [#storetooloptions]

Getter for current tool options.

```ts
console.log(store.toolOptions);
// { strokeWidth: 50, stroke: 'red', opacity: 0.4 }
```

For more details, see [Drawing Tool Documentation](/docs/drawing).

## Working with elements [#working-with-elements]

### store.selectedElements [#storeselectedelements]

Returns array of currently selected elements on the current page.

```ts
const firstSelected = store.selectedElements[0];
```

### store.selectElements(ids) [#storeselectelementsids]

Selects elements on the canvas by their ids.

```ts
store.selectElements([element1.id, element2.id]);

// clear selection and unselect all elements
store.selectElements([]);
```

### store.deleteElements(ids) [#storedeleteelementsids]

Remove elements from the store.

```ts
store.deleteElements([element1.id, element2.id]);
```

### store.getElementById(id) [#storegetelementbyidid]

Finds element in the store by id:

```ts
const element = store.getElementById('some-id');
element.set({ x: 0 });
```

### store.groupElements(\[element1.id, element2.id]) [#storegroupelementselement1id-element2id]

Group elements. It will create a new element with type `group` and will move all passed elements inside it.

```ts
const ids = store.selectedElements.map((el) => el.id);
store.groupElements(ids);

// optionally you can use second argument to set properties of a group
store.groupElements(ids, { id: 'group-id' });
```

### store.ungroupElements(\[element1.id, element2.id]) [#storeungroupelementselement1id-element2id]

Ungroup elements. It will move all elements inside group to the page and remove the group.

```ts
const id = store.selectedElements[0].id;
store.ungroupElements([id]);
```

## History [#history]

### store.history.canUndo [#storehistorycanundo]

Can we undo state?

### store.history.undo() [#storehistoryundo]

Undo last changes

```ts
store.activeElements[0].set({ x: 10 });
store.history.undo();
```

### store.history.redo() [#storehistoryredo]

Redo changes.

```ts
// cancel changes
store.history.undo();

// apply changes again
store.history.redo();
```

### `store.history.transaction(async () => {})` [#storehistorytransactionasync---]

Batch several actions into one history entry.

```ts
store.history.transaction(async () => {
  const element = store.activePage.addElement({
    type: 'text',
    text: 'loading',
  });
  const text = await serverRequest();
  element.set({ text });
});
```

### `store.history.ignore(async () => {})` [#storehistoryignoreasync---]

Run transaction that should be ignored in history.

```ts
store.history.ignore(() => {
  // that change will NOT create a new history point
  element.set({ x: 0, y: 0 });
});
```

### store.history.startTransaction() [#storehistorystarttransaction]

Create a new history transaction. After that command all changes will be recorded as one history point.

### store.history.endTransaction() [#storehistoryendtransaction]

Finish created transaction and record all changes as one history point.

### store.history.clear() [#storehistoryclear]

Clear history.

## Serializations [#serializations]

### store.toJSON() [#storetojson]

Save store into plain object.

```ts
const json = store.toJSON();

// your own function to save JSON somewhere
saveIntoBackend(JSON.stringify(json));
```

### store.loadJSON(json, keepHistory?) / store.loadJSON(json, options?) [#storeloadjsonjson-keephistory--storeloadjsonjson-options]

Load passed json into the store. It will update all properties, pages and elements. By default loading JSON into the store will reset undo/redo history (so a user can't undo it). You can use `keepHistory` argument, if you want to preserve the history.

The second argument can also be an options object (`{ keepHistory?, modernizeTextBackground? }`). Pass `modernizeTextBackground: true` to force the modern per-line rich-text background render on pre-v3 documents — by default, loading a `schemaVersion < 3` design with `backgroundEnabled: true` preserves its pre-v3 full-rect look pixel-exact.

```ts
import { createStore } from 'polotno/model/store';
const store = createStore({
  key: 'YOUR_API_KEY', // you can create it here: https://polotno.com/cabinet/
  // you can hide back-link on a paid license
  // but it will be good if you can keep it for Polotno project support
  showCredit: true,
});

// save to JSON at some point of time
const json = store.toJSON();

// load from JSON
// remember that "json" should be a javascript object
// if you have a json string, you may need to parse it - JSON.parse(string);
store.loadJSON(json);

// load JSON but save previous undo history
// a user can undo this action
store.loadJSON(json, true);

// force modern per-line text backgrounds when loading pre-v3 designs
store.loadJSON(oldJson, { modernizeTextBackground: true });
```

## Events [#events]

### `store.on('change', () => {})` [#storeonchange---]

Listen to any changes in the store. The event may trigger frequently on some operations like resize or dragging. `store.on()` returns an unsubscribe function.

```ts
// unsubscribe function
const off = store.on('change', () => {
  console.log('something changed');
});
// that line will unsubscribe from the event
off();

// write a function for throttle saving
let timeout: any = null;
const requestSave = () => {
  // if save is already requested - do nothing
  if (timeout) {
    return;
  }
  // schedule saving to the backend
  timeout = setTimeout(() => {
    // reset timeout
    timeout = null;
    // export the design
    const json = store.toJSON();
    // save it to the backend
    fetch('https://example.com/designs', {
      method: 'POST',
      body: JSON.stringify(json),
    });
  }, 1000);
};

// request saving operation on any changes
store.on('change', () => {
  requestSave();
});
```

## Export [#export]

### store.waitLoading() [#storewaitloading]

Wait until all resources (images, fonts, etc) are loaded and displayed on the canvas.

```ts
// import data
store.loadJSON(json);
// wait for loading
await store.waitLoading();
// do export
const url = await store.toDataURL();
```

### await store.toDataURL() [#await-storetodataurl]

Export store into image in base64 URL format

```ts
// default export
await store.toDataURL();

// make exported image 2x bigger (higher quality)
await store.toDataURL({ pixelRatio: 2 });

// make small export for preview
// quickMode will skip some "perfect rendering" calculations
await store.toDataURL({ pixelRatio: 0.2, quickMode: true });

// ignore page background on export
await store.toDataURL({ ignoreBackground: true });

// export as jpg
await store.toDataURL({ mimeType: 'image/jpeg' });

// control jpg compression (0-1 range, defaults to browser value)
await store.toDataURL({ mimeType: 'image/jpeg', quality: 0.85 });

// export only required page
await store.toDataURL({ pageId: store.pages[1].id });

// export with page bleed
await store.toDataURL({ includeBleed: true });

// embed custom DPI metadata (for PNG/JPEG only)
await store.toDataURL({ dpi: 300 });

// control DPI metadata embedding behavior
await store.toDataURL({ dpi: 300, dpiMetadata: 'always' });
await store.toDataURL({ dpiMetadata: 'never' }); // skip DPI embedding
```

Use `quality` to control JPEG compression (0-1) whenever you switch `mimeType` to `image/jpeg`. Lower values produce smaller files; keep it above `0.8` for print previews.

**DPI Metadata:** By default (`dpiMetadata: 'auto'`), DPI metadata is embedded into PNG and JPEG images only when DPI differs from 72. Use `dpi` to override the store's DPI value for this export. Set `dpiMetadata: 'never'` to skip embedding entirely, or `dpiMetadata: 'always'` to force embedding even at 72 DPI. DPI metadata is only supported for raster formats (PNG/JPEG).

### await store.saveAsImage() [#await-storesaveasimage]

`saveAsImage` will export the drawing into an image and download it as a local file. By default, it exports just the first page. If you need to export other pages, pass `pageId` property.

```ts
// default export
store.saveAsImage({ fileName: 'polotno.png' });

// export as jpg
store.saveAsImage({ mimeType: 'image/jpeg' });

// control jpg compression (0-1 range, defaults to browser value)
store.saveAsImage({ mimeType: 'image/jpeg', quality: 0.85 });

// make exported image 2x bigger (higher quality)
store.saveAsImage({ pixelRatio: 2 });

// ignore page background on export
store.saveAsImage({ ignoreBackground: true });

// export second page
store.saveAsImage({ pageId: store.pages[1].id });

// export with page bleed
store.saveAsImage({ includeBleed: true });

// embed custom DPI metadata for print workflows
store.saveAsImage({ dpi: 300 });

// control DPI metadata embedding
store.saveAsImage({ dpi: 300, dpiMetadata: 'always' });
```

Tune `quality` for JPEG downloads when you need a balance between file size and preview fidelity. The option ranges from `0` (smallest) to `1` (best quality).

**DPI Metadata:** Use `dpi` to embed resolution metadata for print workflows. By default (`dpiMetadata: 'auto'`), DPI is embedded only when it differs from 72. Set `dpiMetadata: 'never'` to skip embedding, or `dpiMetadata: 'always'` to force it. Applies only to PNG and JPEG formats.

### async store.toPDFDataURL() [#async-storetopdfdataurl]

Export store into PDF file in base64 URL format. You can use it to save to the backend.

```ts
// default export
await store.toPDFDataURL();

// double exported quality
await store.toPDFDataURL({ pixelRatio: 2 });

// ignore page background on export
await store.toPDFDataURL({ ignoreBackground: true });

// export only sub set of pages
await store.toPDFDataURL({ pageIds: [store.pages[0].id, store.pages[2].id] });

// export with custom measurement units for trim boxes
await store.toPDFDataURL({ unit: 'mm' });

// export with page bleed and crop marks
await store.toPDFDataURL({ includeBleed: true, cropMarkSize: 20 });

// track progress
await store.toPDFDataURL({ onProgress: (progress) => console.log(progress) });

// render several pages concurrently while assets load
await store.toPDFDataURL({ parallel: 8 });
```

Set `unit` to align PDF geometry with print-ready specs (`pt`, `mm`, `cm`, or `in`). Increase `parallel` to process multiple pages simultaneously so images and fonts load sooner across large documents; lower it if bandwidth or memory is limited.

### await store.saveAsPDF() [#await-storesaveaspdf]

`saveAsPDF` will export the drawing into PDF and download it as a local file. By default, it exports just the first page. If you need to export other pages, pass `pageId` property.

```ts
// default export
await store.saveAsPDF({ fileName: 'polotno.pdf' });

// change default dpi
// changing DPI will not affect quality of the export. But it may change page size of exported PDF
await store.saveAsPDF({ dpi: 300 }); // default is store.dpi, it equals 72

// ignore page background on export
await store.saveAsPDF({ ignoreBackground: true });

// change export quality
await store.saveAsPDF({ pixelRatio: 2 });

// export with page bleed
await store.saveAsPDF({ includeBleed: true });

// export with page bleed and crop marks
await store.saveAsPDF({ includeBleed: true, cropMarkSize: 20 });

// export using millimeters for bleed and crop mark values
await store.saveAsPDF({ unit: 'cm' });

// export only sub set of pages
await store.saveAsPDF({ pageIds: [store.pages[0].id, store.pages[2].id] });

// track progress
await store.saveAsPDF({ onProgress: (progress) => console.log(progress) });

// render several pages concurrently while assets load
await store.saveAsPDF({ parallel: 8 });
```

Use `unit` when your workflow requires trim boxes in `mm`, `cm`, or `in` instead of the default `pt`. Adjust `parallel` to balance how many pages load assets at once versus overall memory usage.

### await store.toBlob() [#await-storetoblob]

Export store into blob object, it may work faster than `toDataURL` method.

```ts
// default export
await store.toBlob();

// make exported image 2x bigger (higher quality)
await store.toBlob({ pixelRatio: 2 });

// ignore page background on export
await store.toBlob({ ignoreBackground: true });

// export as jpg
await store.toBlob({ mimeType: 'image/jpeg' });

// control jpg compression (0-1 range, defaults to browser value)
await store.toBlob({ mimeType: 'image/jpeg', quality: 0.85 });

// export only required page
await store.toBlob({ pageId: store.pages[1].id });

// export with page bleed
await store.toBlob({ includeBleed: true });

// embed DPI metadata for print workflows
await store.toBlob({ dpi: 300 });

// control DPI metadata embedding
await store.toBlob({ dpi: 300, dpiMetadata: 'always' });
```

When exporting JPEG blobs, pass `quality` (0-1) to match asset pipelines that expect specific compression levels.

**DPI Metadata:** Use `dpi` and `dpiMetadata` to control resolution metadata embedding. By default, DPI is embedded only when it differs from 72. Applies only to PNG and JPEG formats.

### await store.toHTML() [#await-storetohtml]

Warning: this function is beta and may produce inconsistent result.

Export store into HTML string.

```ts
const html = await store.toHTML();

const html2 = await store.toHTML({
  elementHook: ({ dom, element }) => {
    // post process dom representation of the element
    // it is a lite jsx-like object
    // it should have "type", "props" and "children"
    console.log(dom); // first you can log it to see what is inside
    // then you can mutate it based on your custom logic
    dom.props.className = 'my-element';
    return dom;
  },
});
```

### await store.saveAsHTML() [#await-storesaveashtml]

Warning: this function is beta and may produce inconsistent result.

Export store into HTML string and download it as local `.html` file.

### await store.toSVG() [#await-storetosvg]

Warning: this function is beta and may produce inconsistent result.

Export store into SVG string.

```ts
const svg = await store.toSVG({
  fontEmbedding: 'inline', // "inline" or "none"
  elementHook: ({ dom, element }) => {
    // post process dom representation of the element
    dom.className = 'my-element';
    return dom;
  },
});
```

### await store.saveAsSVG() [#await-storesaveassvg]

Export store into SVG string and download it as local `.svg` file.

### await store.toGIFDataURL() [#await-storetogifdataurl]

Export store into GIF image in base64 URL format.

```ts
// default GIF export
const url1 = await store.toGIFDataURL();

// export with full control and progress tracking
const url2 = await store.toGIFDataURL({
  // GIF-specific option
  fps: 10,
  // control size/quality of the exported GIF
  pixelRatio: 1,
});

// export only a single page
await store.toGIFDataURL({ pageId: store.pages[1].id });

// export a subset of pages
await store.toGIFDataURL({
  pageIds: [store.pages[0].id, store.pages[2].id],
});
```

By default the GIF includes every page. Pass `pageId` to render just one page, or `pageIds` to render a subset in order.

### await store.saveAsGIF() [#await-storesaveasgif]

`saveAsGIF` will export drawing into GIF and download it as local file.

```ts
// or save directly as a file with similar options
await store.saveAsGIF({
  fileName: 'polotno.gif',
  fps: 10,
  pixelRatio: 2,
});

// export only a single page
await store.saveAsGIF({ pageId: store.pages[1].id });

// export a subset of pages
await store.saveAsGIF({
  pageIds: [store.pages[0].id, store.pages[2].id],
});
```

### store.setElementsPixelRatio(ratio) [#storesetelementspixelratioratio]

In most scenarios Polotno is rasterizing (converting into bitmap) vector elements such as texts and SVG images. When you do high quality exports, you may want to temporarily increase resolution of rendered elements.

```ts
// make sure all elements are rendered with increased quality
store.setElementsPixelRatio(2);
// do the export
await store.toDataURL({ pixelRatio: 2 });
```

## Animations and video [#animations-and-video]

### store.play() [#storeplay]

Preview animations inside the workspace

```ts
// start playing
store.play();

// start from a specific time
store.play({ startTime: 10000 });

// automatically pause on a specific time
store.play({ endTime: 10000 });

// animate only selected elements
store.play({ animatedElementsIds: store.selectedElements.map((el) => el.id) });

// loop play
store.play({ repeat: true });
```

### store.pause() [#storepause]

Pause playback, keeping the playhead where it is. You can resume from the same position with `store.play({ startTime: store.currentTime })`.

### store.stop() [#storestop]

Stop all animations, reset the current time

### store.currentTime [#storecurrenttime]

Returns current time of playback

### store.setCurrentTime() [#storesetcurrenttime]

Seek to a specific time

### store.setTimingPreview(mode) [#storesettimingpreviewmode]

Controls how the paused canvas treats element timing. In the default `'all'` mode all elements are visible for editing. In `'playhead'` mode the canvas reflects the playhead position — elements outside of their time range are hidden, like during playback. Useful for video-style editing UIs.

```ts
store.setTimingPreview('playhead');
// read the current mode
store.timingPreview; // 'all' | 'playhead'
```

## Working with audio [#working-with-audio]

### `store.addAudio({ src })` [#storeaddaudio-src-]

Add audio into the design

```ts
store.addAudio({
  src: 'https://example.com/audio.mp3',
  // optional props:
  startTime: 0, // define relative point in time of original sound to start the play.
  endTime: 1, // define relative point in time of original sound to stop the play.
  volume: 1, // from 0 to 1
  delay: 0, // in ms the duration between start of video (final scene) and audio play time
});

store.addAudio({
  src: 'https://example.com/audio.mp3',
  delay: 10000, // the audio will start to play after 10 seconds of video
  startTime: 0.5, // if audio duration is 1 min, then we will start to hear it from its 30 secs
});
```

### store.removeAudio(audioId) [#storeremoveaudioaudioid]

Remove audio by its id

### store.audios [#storeaudios]

Access array of added audios of the scene

```ts
store.audios.map((audio) => {
  console.log(audio.id, audio.src);
});
```

## Working with fonts [#working-with-fonts]

For a complete guide on font types and when to use each, see the [Fonts guide](/docs/fonts).

### `store.addFont({ fontFamily, url })` [#storeaddfont-fontfamily-url-]

Add a custom font to the current design. These "design fonts" are saved into exported JSON via `store.toJSON()`. Users can see and remove them from the Text side panel.

For app-wide fonts that shouldn't be stored in JSON, use [Global Fonts](/docs/fonts#global-fonts) instead.

```ts
store.addFont({
  fontFamily: 'MyCustomFont',
  url: serverUrlOrBase64,
});
```

Also you can use a richer API for more control:

```ts
store.addFont({
  fontFamily: 'MyCustomFont',
  styles: [
    {
      src: 'url("pathToNormalFile.ttf")',
      fontStyle: 'normal',
      fontWeight: 'normal',
    },
    {
      src: 'url("pathToBoldFile.ttf")',
      fontStyle: 'normal',
      fontWeight: 'bold',
    },
  ],
});
```

Or you can just register font in the store and then manually add required CSS into the page:

```ts
store.addFont({
  fontFamily: 'MyCustomFont',
});
```

### store.removeFont(name) [#storeremovefontname]

Remove custom font from the store by its name

```ts
store.removeFont('MyCustomFont');
```

### store.loadFont(name) [#storeloadfontname]

Prepare the font to use on the webpage. Text elements inside `Workarea` will use this function automatically. But it can be useful if you want to show a list of fonts somewhere in the UI. `store.loadFont(name)` function will add font to the webpage, so the browser can render correct font.


---

# Utility Functions
URL: https://polotno.com/docs/utils



Polotno provides utility functions organized by module to help with common tasks like SVG manipulation, image processing, geometric calculations, and text measurement. These utilities are designed to work seamlessly with Polotno's data model.

## `polotno/utils/svg` [#polotnoutilssvg]

Utilities for working with SVG strings, converting them to data URLs, and extracting color information.

### `svgToURL(svgString)` [#svgtourlsvgstring]

Converts an SVG string to a data URL that can be used as an image source.

```ts
import { svgToURL } from 'polotno/utils/svg';

const svgString = '<svg>...</svg>';
const dataURL = svgToURL(svgString);
// Returns: "data:image/svg+xml;utf8,<svg>...</svg>"
```

Use this when you need to display an SVG string in an `<img>` tag or use it as an element source.

### `urlToString(url)` [#urltostringurl]

Converts a URL (including data URLs) to a string. Useful for extracting SVG content from element sources.

```ts
import { urlToString } from 'polotno/utils/svg';

const svgString = await urlToString(element.src);
console.log(svgString); // "<svg>...</svg>"
```

Returns a Promise that resolves to the SVG string content. Works with both regular URLs and data URLs.

### `getColors(svgString)` [#getcolorssvgstring]

Extracts all colors found in an SVG string. Returns an array of color values.

```ts
import { getColors, urlToString } from 'polotno/utils/svg';

const svgString = await urlToString(element.src);
const colors = getColors(svgString);
// Returns: ['#ff0000', '#00ff00', 'rgb(0,0,255)']
```

Use this to detect colors in SVG files for building color pickers or validation tools.

### `useSvgColors(src)` [#usesvgcolorssrc]

React hook that extracts colors from an SVG source. Returns an array of detected colors.

```tsx
import { useSvgColors } from 'polotno/utils/svg';

const Toolbar = ({ element }) => {
  const colors = useSvgColors(element.src);
  // colors is an array of color strings
  
  return (
    <div>
      {colors.map((color, i) => (
        <div key={i} style={{ backgroundColor: color }} />
      ))}
    </div>
  );
};
```

The hook automatically handles URL resolution and SVG parsing. Use this in React components when you need reactive color detection.

## `polotno/utils/image` [#polotnoutilsimage]

Utilities for working with image dimensions and calculating crop values.

### `getImageSize(src)` [#getimagesizesrc]

Asynchronously detects the dimensions of an image from a URL or data URL.

```ts
import { getImageSize } from 'polotno/utils/image';

const { width, height } = await getImageSize('https://example.com/image.jpg');
console.log(`Image is ${width}x${height} pixels`);
```

Returns a Promise resolving to `{ width: number, height: number }`. Use this to get image dimensions before setting element properties.

### `getCrop(placeholder, imageSize)` [#getcropplaceholder-imagesize]

Calculates crop values to fit an image into a placeholder element using CSS "cover" behavior. The result fills the placeholder and may crop edges if aspect ratios differ.

```ts
import { getImageSize, getCrop } from 'polotno/utils/image';

// After getting uploaded file as dataURL
const { width, height } = await getImageSize(dataURL);
const crop = getCrop(placeholder, { width, height });

placeholder.set({
  src: dataURL,
  ...crop,
  // crop contains: cropX, cropY, cropWidth, cropHeight (normalized 0-1)
});
```

Crop values are normalized (0-1) and can be applied directly to image elements. For "contain" behavior, resize the element instead of using crop.

## `polotno/utils/math` [#polotnoutilsmath]

Geometric calculation utilities for bounding boxes, center points, and transformations.

### `getTotalClientRect(elements)` [#gettotalclientrectelements]

Calculates the axis-aligned bounding box of one or more elements, accounting for rotation.

```ts
import { getTotalClientRect } from 'polotno/utils/math';

const shapes = store.selectedElements;
const bbox = getTotalClientRect(shapes);
// Returns: { x: number, y: number, width: number, height: number }
```

Use this instead of simple `x + width/2` calculations when elements may be rotated. The bounding box accounts for rotation, giving accurate visual bounds.

### `getClientRect(element)` [#getclientrectelement]

Gets the bounding box of a single element, accounting for its rotation and transformations.

```ts
import { getClientRect } from 'polotno/utils/math';

const box = getClientRect(element);
// Returns: { x: number, y: number, width: number, height: number }

// Use for full-width backgrounds
backgroundEl.set({
  x: 0,
  y: box.y,
  width: element.page.computedWidth,
  height: box.height,
});
```

Returns the visual bounding box after applying rotation. Use this when you need precise element bounds for layout calculations.

### `getCenter(rect)` [#getcenterrect]

Calculates the center point of a rectangle.

```ts
import { getTotalClientRect, getCenter } from 'polotno/utils/math';

const bbox = getTotalClientRect(shapes);
const center = getCenter(bbox);
// Returns: { x: number, y: number }
```

Use this to find rotation centers for groups or multiple selections. Works with any object containing `x`, `y`, `width`, and `height` properties.

### `rotateAroundPoint(shape, angleDelta, center)` [#rotatearoundpointshape-angledelta-center]

Rotates a shape around a specified center point by a given angle delta.

```ts
import { getTotalClientRect, getCenter, rotateAroundPoint } from 'polotno/utils/math';

const bbox = getTotalClientRect(shapes);
const center = getCenter(bbox);
const delta = 45 - (element.rotation || 0);

const newShape = rotateAroundPoint(
  {
    x: element.x,
    y: element.y,
    width: element.width,
    height: element.height,
    rotation: element.rotation || 0,
  },
  delta,
  center
);

element.set(newShape);
```

Returns a new shape object with updated `x`, `y`, and `rotation` values. Use this for programmatic rotation of elements around arbitrary points, such as the center of a selection.

## `polotno/utils/to-svg` [#polotnoutilsto-svg]

Convert Polotno JSON designs to SVG strings for lightweight preview generation.

### `jsonToSVG(options)` [#jsontosvgoptions]

Converts a Polotno JSON design to an SVG string. Useful for generating previews without mounting the full editor.

```ts
import { jsonToSVG } from 'polotno/utils/to-svg';
import { svgToURL } from 'polotno/utils/svg';

// templateJSON is your saved Polotno design
async function getThumbnailURL(templateJSON) {
  const svgString = await jsonToSVG({ json: templateJSON });
  return svgToURL(svgString); // returns data:image/svg+xml;utf8,…
}
```

Returns a Promise resolving to an SVG string. SVG rendering is in beta and may produce slightly different results compared to canvas rendering, but works well for preview thumbnails.

## `polotno/utils/to-canvas` [#polotnoutilsto-canvas]

Render individual elements to canvas elements for custom export or processing.

### `unstable_elementToCanvas(elementId, options?)` [#unstable_elementtocanvaselementid-options]

Renders a single element to an HTML canvas element. Returns a Promise resolving to a canvas.

```ts
import { unstable_elementToCanvas } from 'polotno/utils/to-canvas';

const canvas = await unstable_elementToCanvas(store.selectedElements[0].id);
const dataURL = canvas.toDataURL();
```

**Options:**

| Option       | Type   | Default | Description                                                       |
| ------------ | ------ | ------- | ----------------------------------------------------------------- |
| `pixelRatio` | number | 1       | Output resolution multiplier. Use `2` for retina-quality exports. |

Use `pixelRatio` to control the output resolution. This is useful when the workspace is small on screen but you need a higher-resolution preview:

```ts
// Higher-resolution render at 2x
const canvas = await unstable_elementToCanvas(store.selectedElements[0].id, {
  pixelRatio: 2,
});
```

<Callout type="warning" title="Resolution not guaranteed">
  Higher `pixelRatio` does not guarantee higher quality for all elements. The function renders from the current workspace state, so if the workspace is scaled down, some elements may still use low-resolution or cached textures. For reliable high-resolution output, use the store-level export methods (`store.toDataURL`, `store.saveAsImage`) instead.
</Callout>

> **Note**: This function is experimental and marked as `unstable_`. It may change in future versions. Use with caution in production code.

The canvas can be used for further processing, conversion to images, or custom export workflows.

## `polotno/utils/measure-text` [#polotnoutilsmeasure-text]

Measure text dimensions to check overflow or calculate dynamic layouts.

### `measureText(options)` [#measuretextoptions]

Calculates how much space text will occupy given specific styling properties. Useful for checking if text will overflow a container or for dynamic layout calculations.

```ts
import { measureText } from 'polotno/utils/measure-text';

// Option 1: Pass a Polotno text element
const textElement = store.selectedElements[0];
const result = await measureText(textElement);

// Option 2: Pass text properties directly
const result = await measureText({
  text: 'Hello World',
  width: 200,
  fontSize: 16,
  fontFamily: 'Arial',
  richTextEnabled: true, // optional, defaults to global setting
});

console.log(`Text height: ${result.height}px`);
```

Returns a Promise resolving to `{ height: number }`. The function automatically uses HTML rendering if `richTextEnabled` is true (or uses the global setting if not specified), otherwise falls back to canvas-based measurement.

> **Note**: This function is experimental and may change in future versions.

## `polotno/pages-timeline/page-preview` [#polotnopages-timelinepage-preview]

Hook for building your own pages timeline / thumbnail strip without re-implementing preview rendering.

### `usePagePreview({ page, ref })` [#usepagepreview-page-ref-]

React hook that returns a thumbnail data URL for a single page. It automatically tracks whether your container is visible, queues the render alongside other previews, and re-renders when the page content changes.

```tsx
import * as React from 'react';
import { usePagePreview } from 'polotno/pages-timeline/page-preview';

const PageThumb = ({ page }) => {
  const ref = React.useRef<HTMLDivElement>(null);
  const preview = usePagePreview({ page, ref });

  return (
    <div ref={ref} style={{ width: 120, height: 80 }}>
      {preview ? <img src={preview} alt={`Page ${page.id}`} /> : null}
    </div>
  );
};
```

Pass the page object from `store.pages` and a ref attached to the element that should be observed for visibility. The hook returns `null` until the first render completes, then a `data:` URL of the page thumbnail.

Use this when the default `<PagesTimeline />` component doesn't fit your UI and you want to render your own page navigator with the same lazy/queued thumbnail behavior.

## `polotno/utils/l10n` [#polotnoutilsl10n]

Localization utilities for translating UI strings.

### `t(key)` [#tkey]

Translates a localization key to the current language string.

```tsx
import { t } from 'polotno/utils/l10n';

const App = () => {
  return <div>{t('sidePanel.yourLabel')}</div>;
};
```

Use this in custom components to access Polotno's translation system. See [Editor Configuration](/docs/editor-configuration) for details on setting up translations.


---

# Cloud Render API
URL: https://polotno.com/docs/cloud-render-api





## What is Cloud Render API? [#what-is-cloud-render-api]

Using Polotno SDK, you can generate images directly on the client. But sometimes you need to generate images on the backend. For example, if you want to generate a 1,000 images with different text on it or if you want to simply offload rendering work from the client.

Polotno Cloud Render API is a managed rendering service that allows you to generate images, PDFs, and videos in the cloud without any backend infrastructure. You can use it to generate exports on the fly or to generate them in bulk for automated design workflows.

<img alt="Cloud Render" src="__img0" />

### Pricing [#pricing]

Cloud Render API is available for any subscribers at an additional [price](https://polotno.com/sdk/pricing).

## Before you start [#before-you-start]

(!) Important: all finished jobs will expire in 1 week. Such jobs will be deleted from the database and all render artifacts (images, PDF, videos, etc) are removed from file storage. Make sure to download the export result. If you need a persistent file store, please [contact us](https://polotno.com/contact).

## What does it look like? [#what-does-it-look-like]

### 1. Create render job [#1-create-render-job]

Send a POST request to schedule a rendering job.

```ts
const req = await fetch('https://api.polotno.com/api/renders?KEY=YOUR_API_KEY', {
  method: 'POST',
  headers: {
    // it is important to set a json content type
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    // polotno json from store.toJSON()
    design: json,
    // here you can pass other render options
    pixelRatio: 1,
    // see below for full details of options
  }),
});

const job = await req.json();

console.log(job);
```

It will return a JSON like this:

```json
{
  "id": "fp1f2rtva",
  "status": "scheduled",
  "output": null,
  "error": "",
  "created_at": "2024-05-15T01:41:55.913628+00:00",
  "completed_at": null,
  "started_at": null,
  "updated_at": null,
  "progress": 0,
  "logs": ""
}
```

### Check render job status [#check-render-job-status]

```ts
// replace jobId with real id of the job
const req = await fetch(`https://api.polotno.com/api/renders/jobId?KEY=YOUR_API_KEY`);
const job = await req.json();

console.log(job);

if (job.status === 'done') {
  console.log(job.output); // link to file, valid only for 7 days after job complete
}
```

### Options [#options]

* **design**: json (required) — data from Polotno export `store.toJSON()`. You can generate such JSON on the fly on your backend (e.g. replace text dynamically).
* **format**: string — file format of generated result. One of: `png` (default), `jpeg`, `pdf`, `gif`, `mp4`.
* **webhook**: string — URL to receive HTTP POST notifications with the full job payload.
* **pixelRatio**: number — quality modifier. `0.5` reduces width/height by 2; values > 1 increase quality (and size).
* **ignoreBackground**: boolean — remove page background on export (default: false).
* **dpiMetadata**: string — control DPI metadata embedding for images. One of: `auto` (default), `always`, `never`.
* **includeBleed**: boolean — render bleed areas (default: false).
* **skipFontError**: boolean — continue if font loading fails (default: false).
* **skipImageError**: boolean — continue if image loading fails (default: false).
* **textOverflow**: string — overwrite [text overflow](/docs/text-overflow) logic. Default: `change-font-size`. Other values: `resize`, `ellipsis`.
* **vector**: boolean — make `pdf` in vector format (selectable text). Alpha feature (default: false).
* **color**: object — control color space and profile:

```json
{
  "color": {
    "space": "CMYK",
    "profile": "FOGRA39"
  }
}
```

### See a list of created jobs [#see-a-list-of-created-jobs]

```ts
const req = await fetch('https://api.polotno.com/api/renders/list?KEY=YOUR_API_KEY&page=1&per_page=100');
const job = await req.json();

console.log(job.renders);
```

### Synchronous request [#synchronous-request]

Use `Prefer: 'wait'` for quick renders (e.g., image). The request may still return before completion for long renders (e.g., video).

```ts
const req = await fetch('https://api.polotno.com/api/renders?KEY=YOUR_API_KEY', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Prefer: 'wait'
  },
  body: JSON.stringify({
    design: json,
    pixelRatio: 1,
  }),
});

const job = await req.json();

if (job.status === 'error' || job.status === 'done') {
  // handle result
} else {
  // job may still be running; poll status
}
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-cloud-render" />


---

# Import from Figma
URL: https://polotno.com/docs/figma-import





Polotno can import designs from Figma using the [SVG Import](/docs/svg-import) feature. The process is straightforward: export your Figma frame as SVG, then import it into Polotno.

## Step 1: Select a Frame in Figma [#step-1-select-a-frame-in-figma]

In Figma, select the frame you want to export. Make sure everything you need is inside that frame.

## Step 2: Export as SVG [#step-2-export-as-svg]

In the right panel, find the **Export** section and select **SVG** as the format.

<img src="/docs/figma-import/figma-export-svg.webp" alt="Figma export panel with SVG selected" style="{ display: 'block', margin: '0 auto', maxWidth: '300px', width: '100%' }" />

Before exporting, click the &#x2A;*...** button to open additional export options.

<img src="/docs/figma-import/figma-export-options.webp" alt="Figma export options" style="{ display: 'block', margin: '0 auto', maxWidth: '500px', width: '100%' }" />

### Export Options [#export-options]

<Callout type="warn">
  **"Outline Text" must be OFF** if you want editable text in Polotno. When "Outline Text" is enabled, text is converted into vector paths — it will look visually accurate, but you won't be able to edit the text content. You may still drag, resize, and recolor outlined text elements.
</Callout>

* **Outline Text** — Toggle **OFF** for editable text. Toggle ON if visual fidelity matters more than editability.
* **Include "id" attribute** — Toggle **ON** to preserve layer names from Figma in the imported design.

## Step 3: Import SVG into Polotno [#step-3-import-svg-into-polotno]

Once you have the SVG file, use the `@polotno/svg-import` package to load it into Polotno:

```typescript
import { svgToJson } from '@polotno/svg-import';

async function importFigmaSVG(file: File) {
  const svgContent = await file.text();
  const json = await svgToJson({ svg: svgContent });
  store.loadJSON(json);
}
```

For full details on SVG import options and troubleshooting, see the [SVG Import documentation](/docs/svg-import).

## Tips [#tips]

* **One frame at a time** — Export and import each frame separately for best results.
* **Flatten complex effects** — Figma effects like advanced blurs or blend modes may not translate perfectly. Simplify where possible.
* **Check text after import** — Verify that text elements are editable and display correctly in Polotno.


---

# Large Format & High-Resolution Exports
URL: https://polotno.com/docs/hd-exports



Large format printing requires high-resolution exports that can exceed browser rendering capabilities. This guide covers strategies for exporting designs at print-ready quality for banners, posters, and other large format applications.

## Quick Start (TL;DR) [#quick-start-tldr]

* Decide rendering: **Client** (desktop, ≤8k px/side) or **Server/Vector** (>8k or mobile).
* Client path: set `pixelRatio` 2–4; test on target hardware.
* Print checks: source images must meet `physical inches × target DPI` on each side.
* Vector output options:
  * **Client-side**: export **SVG/HTML** (resolution-independent, feature-dependent).
  * **Server-side**: export **vector PDF** via **Cloud Render API** (`format: 'pdf'`, `vector: true`) or `@polotno/pdf-export`.
* Swap to high-res assets just before export; keep previews in the editor.

## The Challenge [#the-challenge]

Large format designs often require resolutions that browsers cannot render directly. For example:

* **5 × 10 feet banner at 200 DPI** = 12,000 × 24,000 pixels
* **10 × 10 feet banner at 200 DPI** = 24,000 × 24,000 pixels

Browsers cap canvas size by browser/OS/hardware, typically **4,000–16,000 pixels** per dimension. Polotno doesn’t cap exports; failures come from browser and hardware limits.

## Browser Rendering Limits [#browser-rendering-limits]

Canvas rendering limits depend on:

* **Browser**: Chrome, Firefox, Safari have different maximum canvas sizes
* **Operating system**: macOS, Windows, Linux handle memory differently
* **Hardware**: GPU memory and available RAM affect practical limits
* **Typical range**: 4,000–16,000 pixels per dimension

When exports exceed these limits, browsers may:

* Fail to render the canvas
* Crash the tab or browser
* Produce corrupted or incomplete exports

## Choosing Your Approach [#choosing-your-approach]

Select a rendering strategy based on your use case, target audience, and design complexity.

### Decision Cheatsheet [#decision-cheatsheet]

* **Client (desktop, ≤8k px/side)**: real-time, fast; use `pixelRatio` 2–4.
* **Server/Vector (>8k, mobile, or critical print)**: Cloud Render API, `@polotno/pdf-export`, or SVG/HTML (when supported).
* **Hybrid**: detect device + design complexity; fall back to server/vector when near limits.

### Client-Side Rendering [#client-side-rendering]

**Best for:**

* Designs up to \~8,000 pixels per dimension
* Users with powerful desktop computers
* Smaller print formats (business cards, flyers, small posters)
* Real-time preview and instant exports

**Limitations:**

* May fail on mobile devices or low-end hardware
* Memory-intensive for very large exports
* Export time increases with size

### Server-Side Rendering [#server-side-rendering]

**Best for:**

* Designs exceeding 8,000 pixels per dimension
* Mobile or low-end device users
* Guaranteed consistency across devices
* High-volume automated workflows
* Vector PDF exports (resolution-independent)

**Options:**

1. **Cloud Render API** — managed service, no infrastructure
2. **Node.js with Polotno SDK** — full control, requires server setup

### Hybrid Approach [#hybrid-approach]

Detect device capabilities and route exports accordingly:

```ts
const isHighEndDevice = navigator.hardwareConcurrency >= 8 && 
                       navigator.deviceMemory >= 8;

const exportDesign = async (store, pixelRatio = 2) => {
  const maxSide = Math.max(store.width, store.height) * pixelRatio;
  
  if (maxSide > 8000 || !isHighEndDevice) {
    // Use server-side rendering
    return await exportViaCloudAPI(store);
  } else {
    // Use client-side rendering
    return await store.saveAsImage({ pixelRatio });
  }
};
```

## Client-Side High-Quality Export [#client-side-high-quality-export]

Use `pixelRatio` to increase export resolution without changing canvas dimensions. Higher values produce larger output files with better quality.

### Understanding pixelRatio [#understanding-pixelratio]

`pixelRatio` multiplies the canvas dimensions for export:

```ts
// Canvas: 1200 × 1200 px
// Export with pixelRatio: 2 → Output: 2400 × 2400 px
// Export with pixelRatio: 4 → Output: 4800 × 4800 px
await store.saveAsImage({ pixelRatio: 2 });
```

**Important**: `pixelRatio` increases rendered pixels (quality). `dpi` changes physical sizing (PDF page size and ruler units) and DPI metadata for PNG/JPEG. See [Units and Measures](/docs/units-and-measures) for details.

### Practical Limits [#practical-limits]

Start with `pixelRatio: 2` for high quality. Increase to `4` or `8` for very large formats, but test on target devices:

```ts
// 4ft × 4ft banner at 200 DPI = 9,600 × 9,600 pixels
// Editor canvas: 1,200 × 1,200 px (manageable size)
store.setSize(1200, 1200);

// Export at 8× quality to reach 9,600px output
await store.saveAsImage({ pixelRatio: 8 });
```

**Warning**: Very high `pixelRatio` values (8+) may cause browser crashes on some devices. Test thoroughly and consider server-side rendering for critical workflows.

### Complete Client-Side Example [#complete-client-side-example]

```ts
// Setup: 4ft × 4ft banner at 200 DPI
const widthInches = 48; // 4 feet
const heightInches = 48;
const targetDPI = 200;

// Calculate manageable editor size (use 72 DPI for editor)
const editorWidth = widthInches * 72;  // 3,456 px
const editorHeight = heightInches * 72; // 3,456 px

store.setSize(editorWidth, editorHeight);

// Calculate pixelRatio for 200 DPI export
// PDF uses 72 DPI internally, so: pixelRatio = targetDPI / 72
const pixelRatio = targetDPI / 72; // ≈ 2.78

// Export high-quality image
await store.saveAsImage({ 
  pixelRatio: pixelRatio,
});
```

## Editing at Scale (rulers and DPI in the editor) [#editing-at-scale-rulers-and-dpi-in-the-editor]

Use a smaller canvas for stability, but keep rulers showing the real physical size:

```ts
// Target: 10ft × 10ft (120in × 120in), edit at 1:10 scale
const scale = 0.1;
const targetInches = 120;
const editorDPI = 72; // screen DPI

// Proxy canvas: 12in × 12in → 864 × 864 px
store.setSize(targetInches * scale * editorDPI, targetInches * scale * editorDPI);

// Make rulers read 120 inches while canvas is 12 inches
store.setUnit({
  unit: 'in',
  dpi: editorDPI * scale, // 72 * 0.1 = 7.2; 864px/7.2 ≈ 120in on rulers
});
```

At export time, use the real target DPI (e.g., 200) via `pixelRatio` or server/vector rendering. More on units and DPI: [Units and Measures](/docs/units-and-measures).

### Bitmap PDF export: page size vs quality [#bitmap-pdf-export-page-size-vs-quality]

Client-side PDF export is a **bitmap PDF** (each page is a raster image inside a PDF container). Two parameters matter:

* **Page size (real-world inches)** comes from `dpi`: ( inches = pixels / dpi )
* **Render quality** comes from `pixelRatio`: ( effectiveDPI \approx dpi \times pixelRatio )

#### Simple: export a print-ready bitmap PDF [#simple-export-a-print-ready-bitmap-pdf]

```ts
await store.saveAsPDF({
  fileName: 'design.pdf',
  pixelRatio: 2,
});
```

#### Large PDF from a proxy canvas (scale edit → scale export) [#large-pdf-from-a-proxy-canvas-scale-edit--scale-export]

If you edit a 10ft × 10ft banner as a 1:10 proxy (864 × 864 px), export a 120-inch PDF page by using the same scaled DPI, then compensate quality via `pixelRatio`:

```ts
const scale = 0.1;
const targetInches = 120;
const editorDPI = 72;

// Proxy canvas: 864 × 864 px
store.setSize(targetInches * scale * editorDPI, targetInches * scale * editorDPI);
store.setUnit({ unit: 'in', dpi: editorDPI * scale });

const targetDPI = 200;
const exportDPI = editorDPI * scale; // 7.2 → 864px/7.2 = 120 inches page size

await store.saveAsPDF({
  fileName: 'banner.pdf',
  dpi: exportDPI, // controls PDF page size
  pixelRatio: targetDPI / exportDPI, // effectiveDPI ≈ 200
});
```

> **Warning**: For large formats this may require a very large `pixelRatio` (and lots of memory). Prefer server-side rendering or vector PDF for reliability.

> **Note**: If the browser fails at the requested quality, Polotno will automatically retry bitmap PDF export at a lower quality to improve success rates.

See [PDF Export](/docs/pdf-export) for bleed, crop marks, and more options.

## Asset Swapping Strategy [#asset-swapping-strategy]

Use low-resolution preview images in the editor for performance, then swap to high-resolution versions before export.

### Store High-Resolution References [#store-high-resolution-references]

Store high-res URLs in element `custom` metadata:

```ts
// When adding images, store both preview and high-res URLs
element.set({ 
  src: 'https://example.com/preview-800px.jpg', // Fast loading for editor
  custom: { 
    highResSrc: 'https://example.com/original-5000px.jpg' // Full resolution for export
  }
});
```

### Swap Before Export [#swap-before-export]

Replace preview images with high-resolution versions before exporting:

```ts
// Collect all image elements with high-res sources
const originalSrcs = [];

store.pages.forEach(page => {
  page.children.forEach(el => {
    if (el.type === 'image' && el.custom?.highResSrc) {
      // Store original preview URL
      originalSrcs.push({ el, src: el.src });
      // Swap to high-resolution
      el.set({ src: el.custom.highResSrc });
    }
  });
});

// Export with high-quality assets
await store.saveAsImage({ pixelRatio: 4 });

// Revert to preview images for editor performance
originalSrcs.forEach(({ el, src }) => {
  el.set({ src });
});
```

### Validate Image Resolution [#validate-image-resolution]

Use `getImageSize` to check if an image meets the target DPI and physical size:

```ts
import { getImageSize } from 'polotno/utils/image';

const validateImageResolution = async (src, targetDPI, widthInches, heightInches) => {
  const requiredWidth = widthInches * targetDPI;
  const requiredHeight = heightInches * targetDPI;
  const { width, height } = await getImageSize(src);

  const isSufficient = width >= requiredWidth && height >= requiredHeight;
  if (!isSufficient) {
    console.warn(
      `Image resolution (${width}×${height}) may be insufficient ` +
      `for ${widthInches}"×${heightInches}" at ${targetDPI} DPI ` +
      `(requires at least ${requiredWidth}×${requiredHeight}px)`
    );
  }
  return isSufficient;
};
```

## Vector PDF Export [#vector-pdf-export]

Vector PDFs are resolution-independent and avoid pixel limits. Use Cloud Render API (hosted) or the Node package (self-hosted).

### Cloud Render API [#cloud-render-api]

```ts
// 10ft × 10ft banner - no pixel limits with vector PDF
const json = store.toJSON();

const response = await fetch('https://api.polotno.com/api/renders?KEY=YOUR_API_KEY', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    design: json,
    format: 'pdf',
    vector: true, // Enable vector output
  }),
});

const job = await response.json();

// Poll for completion
const checkStatus = async () => {
  const statusRes = await fetch(
    `https://api.polotno.com/api/renders/${job.id}?KEY=YOUR_API_KEY`
  );
  const status = await statusRes.json();
  
  if (status.status === 'done') {
    console.log('Download:', status.output);
  } else if (status.status === 'error') {
    console.error('Export failed:', status.error);
  } else {
    // Still processing, check again
    setTimeout(checkStatus, 2000);
  }
};

checkStatus();
```

See [Cloud Render API](/docs/cloud-render-api) for complete API reference.

### Node Package (@polotno/pdf-export) [#node-package-polotnopdf-export]

```ts
import { jsonToPDF } from '@polotno/pdf-export';

const json = store.toJSON();
await jsonToPDF(json, './output.pdf');
```

See [Node Package](/docs/pdf-export) for complete API reference.

## SVG and HTML Export Alternatives [#svg-and-html-export-alternatives]

See dedicated docs for details: [SVG Export](/docs/import-and-export#html-and-svg-export) and [HTML Export](/docs/import-and-export#html-and-svg-export). Use PNG/JPEG or PDF for pixel-perfect fidelity.

## Example: 10ft × 10ft Banner (120 × 120 inches @ 200 DPI) [#example-10ft--10ft-banner-120--120-inches--200-dpi]

**Recommended (vector PDF, server):**

* Set JSON `width/height` to `120 * 72` (PDF points) and call Cloud Render API with `vector: true`.
* Source images must be \~24,000 px per side to stay sharp at 200 DPI.

**Client attempt (use only for testing on strong desktops):**

* Edit at a reduced canvas (e.g., 1,200 × 1,200 px), then export with high `pixelRatio` (e.g., 20). Expect failures/crashes; prefer server/vector.

## Best Practices [#best-practices]

### Editor Performance [#editor-performance]

* **Use smallest images possible** in the editor for fast loading and smooth interaction
* Store high-resolution references in `custom` metadata
* Swap to high-res only during export
* Polotno automatically optimizes images, but smaller source images improve performance

### Asset Management [#asset-management]

* **Store high-res URLs separately** — don't load full-resolution images in the editor
* **Validate resolution** — check image dimensions against target export requirements
* **Warn users early** — notify if uploaded images are insufficient for target DPI
* **Use CDN** — serve high-resolution assets from a content delivery network

### Export Strategy [#export-strategy]

* **Test on target devices** — verify client-side exports work on your users' hardware
* **Set appropriate timeouts** — server exports may take 5+ minutes for very large files
* **Monitor memory usage** — large exports consume significant RAM
* **Provide progress feedback** — show export progress for long-running operations

## Troubleshooting [#troubleshooting]

### Canvas Exceeds Browser Limits [#canvas-exceeds-browser-limits]

**Symptom**: Export fails, browser crashes, or produces corrupted output.

**Solutions**:

* Reduce canvas dimensions or `pixelRatio`
* Use server-side rendering (Cloud Render API or Node.js)
* Use vector PDF/SVG/HTML export (no pixel limits)

### Server Export Timeout [#server-export-timeout]

**Symptom**: Server export requests timeout before completion.

**Solutions**:

* Increase HTTP timeout limits (5+ minutes for very large exports)
* Use async job polling instead of synchronous requests
* Optimize design complexity
* Consider Cloud Render API with webhook notifications

## Related [#related]

* [PDF Export](/docs/pdf-export) — client-side PDF export with quality settings
* [Cloud Render API](/docs/cloud-render-api) — server-side vector PDF export
* [Units and Measures](/docs/units-and-measures) — DPI, pixelRatio, and unit conversion
* [Import and Export](/docs/import-and-export) — overview of all export formats
* [Store API](/docs/store) — complete export API reference


---

# Import and Export
URL: https://polotno.com/docs/import-and-export



Polotno offers comprehensive import and export capabilities for designs, from open JSON format to high-quality images, PDFs, and video exports. The SDK supports both client-side and [server-side rendering](/docs/server-side-image-generation-with-node-js) for automated design generation.

**Import:** JSON (open, developer-friendly format), [SVG](/docs/svg-import), [PDF](/docs/pdf-import), [PSD](/docs/psd-import)

**Export:** JSON, PNG, JPEG, PDF, PPTX, GIF, MP4, HTML, SVG

**Key use cases:** Template systems, programmatic generation, print production, digital graphics, animations, web embedding.

## JSON Import and Export [#json-import-and-export]

Polotno uses an **open JSON format** designed for developer flexibility. You can export, read, modify, and re-import designs programmatically.

**Key features:**

* **Simple, readable format** — JSON structure is straightforward and documented
* **Fully modifiable** — export, modify properties, and re-import
* **Programmatic generation** — create or modify designs in code
* **Template system** — save and load templates, generate variations dynamically

### Export to JSON [#export-to-json]

```ts
const json = store.toJSON();
console.log(json); // readable JSON structure

// modify programmatically
json.pages[0].children[0].text = 'Updated text';

// save or send to backend
localStorage.setItem('design', JSON.stringify(json));
```

### Import from JSON [#import-from-json]

```ts
// load previously saved design
const json = JSON.parse(localStorage.getItem('design'));
store.loadJSON(json);

// import template or generated design
store.loadJSON({
  width: 800,
  height: 600,
  pages: [/* ... */]
});
```

The JSON must follow Polotno's [store structure](/docs/store). See [Design Format](/docs/schema) for the complete field reference, types, and validation.

**Note**: PPTX import isn't first-party yet — for now you can build a converter that emits Polotno JSON, or [contact us](https://polotno.com/contact) to collaborate.

## SVG Import [#svg-import]

Import SVG files into Polotno using the `@polotno/svg-import` package.

```bash
npm install @polotno/svg-import
```

```ts
import { svgToJson } from '@polotno/svg-import';

const json = await svgToJson({ svg: svgContent });
store.loadJSON(json);
```

**Note:** Text converted to paths cannot be restored as editable text. See [SVG Import](/docs/svg-import) for full details and workflow recommendations.

**Try it without code:** [SVG to JSON](/tools/svg-to-json) · [SVG to PDF](/tools/svg-to-pdf) — both run `svgToJson()` in the browser on your own files.

## PDF Import [#pdf-import]

Import PDF files into Polotno using the `@polotno/pdf-import` package.

```bash
npm install @polotno/pdf-import
```

```ts
import { pdfToJson } from '@polotno/pdf-import';

const buffer = await file.arrayBuffer();
const json = await pdfToJson({ pdf: buffer });
store.loadJSON(json);
```

Works both client-side and server-side. See [PDF Import](/docs/pdf-import) for full details.

**Try it without code:** [PDF to JSON](/tools/pdf-to-json) · [PDF to SVG](/tools/pdf-to-svg) · [PDF to HTML](/tools/pdf-to-html) — all three run `pdfToJson()` in the browser on your own files.

## PSD Import [#psd-import]

Import Photoshop `.psd` files into Polotno using the `@polotno/psd-import` package. Layers come through as separate, editable elements: text stays editable text, vector shapes stay vector, raster layers stay images. Masks and unsupported effects are baked per layer so the rest of the document remains separable.

```bash
npm install @polotno/psd-import
```

```ts
import { psdToJson } from '@polotno/psd-import';

const buffer = await file.arrayBuffer();
const json = await psdToJson({ psd: buffer });
store.loadJSON(json);
```

Works both client-side and server-side. See [PSD Import](/docs/psd-import) for full details.

**Try it without code:** [PSD to PNG](/tools/psd-to-png) · [PSD to JPG](/tools/psd-to-jpg) · [PSD to PDF](/tools/psd-to-pdf) · [PSD to SVG](/tools/psd-to-svg) · [PSD to HTML](/tools/psd-to-html) · [PSD to JSON](/tools/psd-to-json) — all six run `psdToJson()` in the browser on your own files.

## Image Export (PNG, JPEG) [#image-export-png-jpeg]

Export designs as PNG or JPEG images. Available client-side and server-side.

```ts
// basic export
await store.saveAsImage();

// with quality control
await store.saveAsImage({ 
  pixelRatio: 2,
  mimeType: 'image/png'
});

// with DPI metadata for print workflows
await store.saveAsImage({
  dpi: 300,
  dpiMetadata: 'auto' // 'auto' | 'always' | 'never'
});

// as data URL or blob
const dataURL = await store.toDataURL();
const blob = await store.toBlob();
```

**DPI Metadata:** PNG and JPEG exports support embedding resolution metadata via the `dpi` parameter (defaults to `store.dpi` value). By default (`dpiMetadata: 'auto'`), metadata is embedded only when DPI differs from 72. Use `dpiMetadata: 'always'` to force embedding or `'never'` to skip it.

## PDF Export [#pdf-export]

Export designs as PDF files. Two paths, both available client-side:

* **Raster** — `store.saveAsPDF()` flattens each page into an image embedded in the PDF.
* **Vector** — `jsonToPDFBlob()` from `@polotno/pdf-export/browser` keeps paths, strokes, and selectable text. Same package supports Node and PDF/X-1a print-ready output.

```ts
// raster — built-in
await store.saveAsPDF({
  includeBleed: true,
  cropMarkSize: 20,
  pixelRatio: 2,
});

// vector — browser entry
import { jsonToPDFBlob } from '@polotno/pdf-export/browser';
const blob = await jsonToPDFBlob(store.toJSON());
```

See [PDF Export](/docs/pdf-export) for the full comparison, bleed/crop marks, PDF/X-1a, spot colors, and the Cloud Render API option.

## GIF Export [#gif-export]

Export animated designs as GIF files. Available client-side and server-side.

```ts
await store.saveAsGIF();

// with custom settings
await store.saveAsGIF({
  fps: 30,
  pixelRatio: 2
});

// export only specific pages
await store.saveAsGIF({
  pageIds: [store.pages[0].id, store.pages[2].id],
});
```

Use `pageId` (single page) or `pageIds` (subset, in order) to limit which pages end up in the GIF. See [Store API](/docs/store#await-storesaveasgif) for the full option list.

## Video Export (MP4) [#video-export-mp4]

Export animated designs as MP4 video files.

**Client-side:** Use `@polotno/video-export` package for browser-based video encoding. See [Video Export](/docs/video-export) for details.

**Server-side:** Use [Cloud Render API](/docs/cloud-render-api).

## HTML and SVG Export [#html-and-svg-export]

Export designs as HTML or SVG for embedding in websites or further processing.

```ts
// export as HTML
const html = await store.toHTML();
await store.saveAsHTML();

// export as SVG
const svg = await store.toSVG();
await store.saveAsSVG();
```

**Note:** May not support all elements or features. For pixel-perfect exports, use PNG/JPEG or PDF.

## PPTX Export (PowerPoint) [#pptx-export-powerpoint]

Export designs as PowerPoint presentations. Multi-page designs become multi-slide presentations.

```ts
await store.saveAsPPTX();
```

See [PPTX Export](/docs/pptx-export) for details.

## Server-Side Rendering [#server-side-rendering]

All export formats can be generated server-side for high-volume or automated workflows.

**Options:**

1. **Node.js with Polotno SDK** — run Polotno in Node.js environment. See [Server-Side Image Generation](/docs/server-side-image-generation-with-node-js).
2. **Cloud Render API** — fully managed rendering service, no infrastructure needed. See [Cloud Render API](/docs/cloud-render-api).

## Complete API Reference [#complete-api-reference]

For all export options and parameters, see [Store API](/docs/store).


---

# PDF Export
URL: https://polotno.com/docs/pdf-export



Polotno offers two PDF export paths:

* **Raster** — `store.saveAsPDF()` / `store.toPDFDataURL()` in the browser, or [`polotno-node`](/docs/server-side-image-generation-with-node-js) on the server. Each page is a flattened image embedded in the PDF.
* **Vector** — [`@polotno/pdf-export`](https://www.npmjs.com/package/@polotno/pdf-export) (browser **or** Node), or the [Cloud Render API](/docs/cloud-render-api) with `vector: true`. Resolution-independent output with selectable text.

<Callout type="info">
  **Try it without code:** The [SVG to PDF](/tools/svg-to-pdf) converter exposes both options — it ships **vector by default** via `@polotno/pdf-export/browser` and offers a one-click bitmap fallback. Drop a file and try both before integrating.
</Callout>

## Choosing raster vs vector [#choosing-raster-vs-vector]

|                      | Raster                                   | Vector                                               |
| -------------------- | ---------------------------------------- | ---------------------------------------------------- |
| **Output**           | Flattened image per page                 | Selectable text, scalable shapes                     |
| **Visual fidelity**  | Identical to canvas                      | May differ slightly (font shaping, effects)          |
| **File size**        | Larger at high `pixelRatio`              | Smaller, resolution-independent                      |
| **Print compliance** | Good with high `pixelRatio`              | Required for PDF/X-1a, spot colors                   |
| **Where it runs**    | Browser, or `polotno-node` on the server | Browser, Node, or Cloud Render API                   |
| **Server required**  | No (browser path)                        | No (browser path); PDF/X-1a needs Node + Ghostscript |

Pick **raster** when you need pixel-perfect parity with the editor canvas. Pick **vector** for selectable text, smaller files, or print-shop deliverables (PDF/X-1a, spot inks, foils). Both can run fully client-side now — vector via the `@polotno/pdf-export/browser` entry.

***

## Raster export [#raster-export]

Browser-side export via `store.saveAsPDF()`. Same options apply to `store.toPDFDataURL()`.

### Quick start [#quick-start]

```ts
await store.saveAsPDF({
  fileName: 'design.pdf',
  includeBleed: true,
  cropMarkSize: 20,
  pixelRatio: 2,
});
```

### Bleed and crop marks [#bleed-and-crop-marks]

Bleed is the extra ink area beyond the trim edge. Crop marks indicate where the print shop should cut.

```ts
// set bleed on the page
store.activePage.set({ bleed: 35 }); // 35px

// show bleed area on the canvas (optional, for editor preview)
store.toggleBleed(true);

// export
await store.saveAsPDF({
  includeBleed: true,
  cropMarkSize: 20, // crop mark length in pixels
});
```

See [Page Bleed](/docs/page-bleed) for working with bleed in the editor.

### Quality [#quality]

Use `pixelRatio` to control resolution. `dpi` affects PDF page dimensions, **not** image quality.

```ts
await store.saveAsPDF({ pixelRatio: 2 }); // recommended for print
await store.saveAsPDF({ pixelRatio: 4 }); // ultra-high
```

See [Units and Measures](/docs/units-and-measures) for DPI details.

### Options [#options]

```ts
await store.saveAsPDF({
  fileName: 'design.pdf',
  includeBleed: true,
  cropMarkSize: 20,
  pixelRatio: 2,
  onProgress: (progress) => console.log(progress),
});
```

See [Store API](/docs/store) for the complete reference.

***

## Vector export [#vector-export]

Three ways to produce vector PDFs. All accept the same Polotno JSON and produce equivalent output for the same input — pick the one that matches your hosting model.

### Browser package: `@polotno/pdf-export/browser` [#browser-package-polotnopdf-exportbrowser]

Convert a design to a vector PDF entirely in the user's browser — no server, no Ghostscript, no API key.

```bash
npm install @polotno/pdf-export
```

```ts
import { jsonToPDFBlob } from '@polotno/pdf-export/browser';

async function exportToPDF(store) {
  const blob = await jsonToPDFBlob(store.toJSON());
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'design.pdf';
  document.body.appendChild(a);
  a.click();
  a.remove();
  URL.revokeObjectURL(url);
}
```

The browser entry also exports `jsonToPDFBytes(json, attrs): Promise<Uint8Array>` for cases where you want raw bytes (IndexedDB, `navigator.share`, WebTransport, etc.).

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-vector-pdf-export" />

#### CORS [#cors]

When the design references remote images, fonts, or SVG sources, the browser fetches those at export time. They must be reachable with CORS:

* **Google Fonts** (`fonts.googleapis.com` and `fonts.gstatic.com`) work out of the box.
* **Custom asset URLs** must be served with `Access-Control-Allow-Origin: *` (or your origin), or pre-fetched and inlined as `data:` URLs in the JSON.

#### Browser limitations [#browser-limitations]

The browser entry **does not** support `attrs.pdfx1a` or `attrs.validate` — those rely on Ghostscript, which has no browser equivalent. Pass them and you'll get a clear runtime error pointing at the Node entry. For PDF/X-1a, spot colors, and Ghostscript-backed validation, see the Node section below.

### Cloud Render API [#cloud-render-api]

Hosted rendering. Send the JSON as a render job with `format: 'pdf'` and `vector: true`.

```ts
const req = await fetch('https://api.polotno.com/api/renders?KEY=YOUR_API_KEY', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    design: store.toJSON(),
    format: 'pdf',
    vector: true,
  }),
});
```

See [Cloud Render API](/docs/cloud-render-api) for full options, polling, webhooks, and CMYK color profiles.

### Node package: `@polotno/pdf-export` [#node-package-polotnopdf-export]

Run the conversion fully offline inside Node 18+. Fits CI jobs, backend services, and desktop tools. Required for PDF/X-1a print-ready output and Ghostscript-backed spot colors.

```bash
npm install @polotno/pdf-export
```

```ts
import fs from 'fs/promises';
import { jsonToPDF } from '@polotno/pdf-export';

const data = JSON.parse(await fs.readFile('./polotno.json', 'utf-8'));

await jsonToPDF(data, './output.pdf');
```

`jsonToPDFBytes(data, attrs): Promise<Uint8Array>` is also exported on the Node entry — useful when you want raw bytes (to upload, attach, etc.) without writing to disk.

#### Bleed and crop marks [#bleed-and-crop-marks-1]

Set `bleed` (pixels) on each page in the JSON, then enable bleed and crop marks at export time.

```ts
// JSON
const data = {
  width: 1080,
  height: 1080,
  pages: [{ background: '...', bleed: 36, children: [/* ... */] }],
};

// export
await jsonToPDF(data, './print-ready.pdf', {
  pdfx1a: true,
  includeBleed: true,
  cropMarkSize: 18, // reserve 18px around the bleed for crop marks
});
```

When `includeBleed` or `cropMarkSize` is set, the output PDF carries correct PDF/X page boxes:

* **MediaBox** — full sheet (trim + bleed + crop-mark margin)
* **BleedBox** — trim + bleed (where ink may cover)
* **TrimBox** — final cut size
* **ArtBox** — same as TrimBox

`TrimBox ⊆ BleedBox ⊆ MediaBox`, per PDF/X spec. RIPs and proofers use these boxes to identify the live area without guessing.

Element coordinates in the JSON stay relative to the trim corner — a `(0, 0)` element still lands at the top-left of the trim. Backgrounds extend automatically into the bleed strip; the crop-mark margin remains unprinted.

#### DPI handling [#dpi-handling]

Coordinates in the JSON are pixels at the specified DPI; PDFs use points (1pt = 1/72 inch). The library converts: `points = pixels × (72 / dpi)`.

```ts
// uses dpi from JSON (or 72 if unspecified)
await jsonToPDF(data, './output.pdf');

// override
await jsonToPDF(data, './output.pdf', { dpi: 150 });
```

A 1920×1080 canvas at 300 DPI exports as 6.4″ × 3.6″; the same canvas at 72 DPI exports as 26.67″ × 15″.

#### PDF/X-1a [#pdfx-1a]

Print-ready output with CMYK conversion, transparency flattening, and font outlining.

```ts
await jsonToPDF(data, './print-ready.pdf', {
  pdfx1a: true,
  validate: true, // optional — verify PDF/X-1a compliance
  metadata: {
    title: 'Catalog Cover',
    author: 'Marketing Team',
    application: 'Polotno Automation 1.0',
  },
});
```

> **Note**: PDF/X-1a conversion requires GhostScript on the host machine — `brew install ghostscript`, `apt-get install ghostscript`, or download from [ghostscript.com](https://www.ghostscript.com/).

#### Spot colors and overprint [#spot-colors-and-overprint]

Map specific fills or strokes to separation inks for foil, Pantone, or varnish workflows. Any element using the matched color is exported with the correct separation ink; CMYK fallbacks ensure predictable previews.

```ts
await jsonToPDF(data, './foil-cover.pdf', {
  pdfx1a: true,
  spotColors: {
    'rgba(255,215,0,1)': {
      name: 'Gold Foil',
      pantoneCode: 'Pantone 871 C', // optional reference
      cmyk: [0, 0.15, 0.5, 0],      // 0–1 range, used as fallback
      overprint: true,
    },
    '#C0C0C0': {
      name: 'Silver Foil',
      cmyk: [0, 0, 0, 0.25],
      overprint: true,
    },
  },
});
```

**Color matching is flexible.** `'#FFD700'`, `'#ffd700'`, `'rgb(255,215,0)'`, and `'rgba(255,215,0,1)'` all match the same color. Works on text, lines, figures (rect, circle, star, blobs), and SVG elements.

**`overprint: true`** tells the press to print the spot ink **on top of** the underlying CMYK rather than knocking it out. Without overprint, a misregistered foil die leaves a visible white halo at the edge. With overprint, CMYK prints continuously through the spot region and the foil stamps over it. This is the standard choice for foil and varnish.

> **Tip**: Verify spot colors in Adobe Acrobat Pro: **Tools → Print Production → Output Preview → Separations**. Use *Simulate Overprinting* to preview how the press will composite the layers.

> **Caveat**: Spot color preservation through PDF/X-1a depends on Ghostscript not flattening transparency in the spot region. Plain figures, lines, text, and simple SVG paths work. SVGs that use `<clipPath>` or `<mask>` may have their spot color flattened to CMYK during pdfx1a conversion. For foil regions, prefer plain shapes or simple SVG paths over masked artwork.

#### Full reference [#full-reference]

For all options and the latest changes, see the [`@polotno/pdf-export` README on npm](https://www.npmjs.com/package/@polotno/pdf-export).

***

## Error handling [#error-handling]

Failures throw a plain `Error` with a `code` — `DESIGN_INVALID` (the schema pre-flight every render runs first), `IMAGE_FAILED`, `FONT_FAILED`, `FETCH_FAILED`, or `EXPORT_FAILED` — plus structured `details` such as `elementId`, `mimeType`, and a fine-grained `details.reason`. Branch on the code, not the message text. See [Error Handling](/docs/error-handling) for the full vocabulary.

## Troubleshooting [#troubleshooting]

**Bleed not visible on canvas?** Use `store.toggleBleed(true)`.

**Raster export looks low quality?** Increase `pixelRatio` to 2 or 4. `dpi` controls page dimensions, not quality.

**Wrong page size?** Adjust the JSON `dpi` value (or pass `dpi` to `jsonToPDF`).

**Spot color rendered as CMYK in the foil region?** Check whether the artwork uses `<clipPath>` or `<mask>` — Ghostscript may flatten transparency groups during PDF/X-1a conversion. Replace with plain shapes or simple paths.

## Related [#related]

* [Page Bleed](/docs/page-bleed) — working with bleed in the editor
* [Cloud Render API](/docs/cloud-render-api) — hosted rendering
* [Server-side image generation with Node.js](/docs/server-side-image-generation-with-node-js) — `polotno-node` for raster export on the server
* [Units and Measures](/docs/units-and-measures) — DPI and unit conversion
* [Store API](/docs/store) — complete export API reference


---

# PDF Import
URL: https://polotno.com/docs/pdf-import





The `@polotno/pdf-import` package converts PDF files into Polotno JSON format, enabling you to import PDF designs into Polotno for further editing.

<Callout type="warn">
  **Beta Feature:** This library is new and may not work correctly for all PDF files. Please [report issues](https://community.polotno.com/c/ask) to help us improve it.
</Callout>

<Callout type="info">
  **Try it without code:** The [PDF to JSON](/tools/pdf-to-json), [PDF to SVG](/tools/pdf-to-svg), and [PDF to HTML](/tools/pdf-to-html) converters run this exact parser in the browser — drop your own file to test it before integrating.
</Callout>

**Importing other formats?** See [SVG Import](/docs/svg-import) and [PSD Import](/docs/psd-import) for the equivalent packages.

## Installation [#installation]

```bash
npm install @polotno/pdf-import
```

## Basic Usage [#basic-usage]

```typescript
import { pdfToJson } from '@polotno/pdf-import';

const json = await pdfToJson({ pdf: buffer });

// Load into Polotno store
store.loadJSON(json);
```

## Node.js Example [#nodejs-example]

```typescript
import { pdfToJson } from '@polotno/pdf-import';
import fs from 'fs';

const buffer = fs.readFileSync('design.pdf');
const json = await pdfToJson({ pdf: buffer });
store.loadJSON(json);
```

## Browser Example [#browser-example]

```typescript
import { pdfToJson } from '@polotno/pdf-import';

async function handleFileUpload(file: File) {
  const buffer = await file.arrayBuffer();
  const json = await pdfToJson({ pdf: buffer });
  store.loadJSON(json);
}
```

`pdfToJson` returns a complete, valid [Design Format](/docs/schema) document, ready for `store.loadJSON()`. See the reference for every field and type.

## Adobe Illustrator (.ai) Support [#adobe-illustrator-ai-support]

Adobe Illustrator `.ai` files are based on the PDF format, so you can import them using the same `pdfToJson()` function.

## Platform Support [#platform-support]

This package works both &#x2A;*client-side (browser)** and &#x2A;*server-side (Node.js)**. All processing runs locally — no data is sent to any external server.

## Demo [#demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-pdf-import" />

## Error Handling [#error-handling]

If a file can't be parsed, the importer throws a plain `Error` with `code: 'IMPORT_FAILED'` and `details.format: 'pdf'`; the low-level parser error is chained as `error.cause`. See [Error Handling](/docs/error-handling).

## Troubleshooting [#troubleshooting]

**Import produces unexpected results:**

* Check if the PDF contains vector elements or rasterized content
* Try re-exporting the PDF from your design tool with different settings

**Missing elements:**

* Some advanced PDF features may not be supported
* Check browser console for warnings

**Need help?** Report issues and get support at [community.polotno.com](https://community.polotno.com/c/ask).


---

# PPTX Export
URL: https://polotno.com/docs/pptx-export



## Overview [#overview]

Polotno supports exporting designs to PowerPoint (PPTX) format, allowing you to create presentation files from your designs. This feature is available through the `@polotno/pptx-export` package.

## Installation [#installation]

First, install the PPTX export package:

```bash
npm install @polotno/pptx-export
```

## Basic Usage [#basic-usage]

Import the package and use the `jsonToPPTX` function to export your design:

```ts
import { jsonToPPTX } from '@polotno/pptx-export';

// Export the current design to PPTX
jsonToPPTX({
  json: store.toJSON(),
  output: 'my-design.pptx',
});
```

### Dynamic Import [#dynamic-import]

If you prefer to load the package dynamically (e.g., to reduce initial bundle size), you can use dynamic imports:

```ts
import('@polotno/pptx-export').then((module) => {
  module.jsonToPPTX({
    json: store.toJSON(),
    output: 'my-design.pptx',
  });
});
```

## API Reference [#api-reference]

### `jsonToPPTX(options)` [#jsontopptxoptions]

Exports a Polotno design to PowerPoint format.

**Parameters:**

* `json` (required): The design JSON from `store.toJSON()`
* `output` (required): The output filename (e.g., `'presentation.pptx'`)

**Example:**

```ts
import { jsonToPPTX } from '@polotno/pptx-export';

const handleExport = () => {
  jsonToPPTX({
    json: store.toJSON(),
    output: 'my-presentation.pptx',
  });
};
```

## Use Cases [#use-cases]

* Convert designs into editable PowerPoint presentations
* Share designs with users who prefer working in PowerPoint
* Create templates that can be further edited in presentation software
* Export multi-page designs as presentation slides

## Notes [#notes]

* Each Polotno page becomes a slide in the PowerPoint presentation
* Text elements remain editable in PowerPoint
* Images are embedded in the presentation file

## Limitations [#limitations]

<Callout type="warn" title="Missing Effects and Features">
  The PPTX export may not support all Polotno effects and features. Some advanced styling, animations, or custom elements might not be fully preserved in the exported PowerPoint file.

  If you encounter any issues or have feedback about missing features, please share your experience in the [Polotno Community](https://community.polotno.com/c/ask).
</Callout>

<Callout type="info" title="Font Embedding">
  PPTX files do **not** embed fonts inside the file. If you use custom fonts in your design, they will be displayed using system fallback fonts when the presentation is opened on another computer, unless those custom fonts are already installed on that system.

  For consistent typography across different devices, consider using common system fonts like Arial, Helvetica, Times New Roman, or Georgia.
</Callout>

## Error Handling [#error-handling]

Export failures throw a plain `Error` with a `code` (`DESIGN_INVALID`, `IMAGE_FAILED`, `EXPORT_FAILED`, `FETCH_FAILED`) and structured `details` such as `elementId`. Branch on the code, not the message text — see [Error Handling](/docs/error-handling).

## Live Demo [#live-demo]

Try out the PPTX export feature in this interactive demo:

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-pptx-export" />


---

# PSD Import
URL: https://polotno.com/docs/psd-import





The `@polotno/psd-import` package converts Photoshop `.psd` files into Polotno JSON format, enabling you to import PSD designs into Polotno for further editing — text stays editable text, vector shapes stay vector, raster layers stay images.

<Callout type="warn">
  **Beta Feature:** This library is new and may not work correctly for all PSD files. Please [report issues](https://community.polotno.com/c/ask) to help us improve it.
</Callout>

<Callout type="info">
  **Try it without code:** The [PSD to PNG](/tools/psd-to-png), [PSD to JPG](/tools/psd-to-jpg), [PSD to PDF](/tools/psd-to-pdf), [PSD to SVG](/tools/psd-to-svg), [PSD to HTML](/tools/psd-to-html), and [PSD to JSON](/tools/psd-to-json) converters run this exact parser in the browser — drop your own file to test it before integrating.
</Callout>

## Installation [#installation]

```bash
npm install @polotno/psd-import
```

## Basic Usage [#basic-usage]

`psdToJson` accepts an `ArrayBuffer` or `Uint8Array` of PSD bytes and returns a Polotno-schema JSON document.

```typescript
import { psdToJson } from '@polotno/psd-import';

const json = await psdToJson({ psd: buffer });

// Load into Polotno store
store.loadJSON(json);
```

The returned object matches the [Design Format](/docs/schema): `{ width, height, fonts, pages, unit, dpi }`.

## Browser Example [#browser-example]

Read bytes from a file input:

```typescript
import { psdToJson } from '@polotno/psd-import';

async function handleFileUpload(file: File) {
  const buffer = await file.arrayBuffer();
  const json = await psdToJson({ psd: buffer });
  store.loadJSON(json);
}
```

## Node.js Example [#nodejs-example]

Read bytes from disk:

```typescript
import { readFile } from 'node:fs/promises';
import { psdToJson } from '@polotno/psd-import';

const buffer = await readFile('./design.psd');
const json = await psdToJson({ psd: buffer });
store.loadJSON(json);
```

## How It Works [#how-it-works]

The goal is to keep as many of the PSD's layers as **separate, editable elements** as possible, instead of flattening the file into a single image. Each PSD layer is mapped to the closest equivalent in the Polotno schema:

* **Text layers** stay as editable text — font family, weight, style, size, color, alignment, line height, and letter spacing carry over.
* **Shape and vector layers** become SVG elements with their fills, gradients, and strokes preserved.
* **Raster layers** become images. When a layer uses effects the schema can't represent natively (gradient/color overlays, gradient maps, hue/saturation, brightness/contrast, …), the effect is baked into that layer's pixels so it still looks right while every other element remains separate.
* **Masks** and **group effects** are applied to the layers underneath them, so masked content and folder-level overlays render correctly without collapsing the document.
* **Blend modes** pass through where the schema supports them; unsupported modes are flattened only with the layers they depend on.

The PSD's pre-rendered composite image is intentionally **not** used — every element stays selectable and editable.

## Platform Support [#platform-support]

This package works both &#x2A;*client-side (browser)** and &#x2A;*server-side (Node.js)**. All processing runs locally — no data is sent to any external server.

## Demo [#demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-psd-import" />

## Error Handling [#error-handling]

If a file can't be parsed, the importer throws a plain `Error` with `code: 'IMPORT_FAILED'` and `details.format: 'psd'`; the low-level parser error is chained as `error.cause`. See [Error Handling](/docs/error-handling).

## Related Imports [#related-imports]

* [SVG Import](/docs/svg-import) — `@polotno/svg-import` for SVG files
* [PDF Import](/docs/pdf-import) — `@polotno/pdf-import` for PDF and Adobe Illustrator files
* [Import & Export overview](/docs/import-and-export)

## Troubleshooting [#troubleshooting]

**Import produces unexpected results:**

* Try simplifying the PSD before importing (flatten unused groups, rasterize complex smart objects)
* Some advanced Photoshop features (3D layers, video layers, complex layer comps) aren't supported
* Check browser console for warnings

**Missing fonts:**

* Fonts are referenced by family name in the imported design; if the font isn't installed where the design renders, the editor or browser will fall back. Install or load the font before rendering for pixel-perfect output.

**Large files:**

* PSDs up to a few hundred MB usually parse fine in the browser. For very large files or bulk processing, run `psdToJson()` in Node.js where memory limits are higher.

**Need help?** Report issues and get support at [community.polotno.com](https://community.polotno.com/c/ask).


---

# Server-side Image Generation with Node.js
URL: https://polotno.com/docs/server-side-image-generation-with-node-js



## Is it possible to generate images from Polotno JSON on the backend? [#is-it-possible-to-generate-images-from-polotno-json-on-the-backend]

Yes, you can leverage the [polotno-node package](https://www.npmjs.com/package/polotno-node).

Using polotno-node you can use most of the [Polotno Store API](/docs/store). The common usage is image export from Polotno JSON:

```js
const fs = require('fs');
// import polotno-node API
const { createInstance } = require('polotno-node');

async function run() {
  // create working instance
  const instance = await createInstance({
    // to create your own API key please go here: https://polotno.com/cabinet
    key: 'nFA5H9elEytDyPyvKL7T',
  });

  // load sample json
  const json = JSON.parse(fs.readFileSync('polotno.json'));
  // here you can manipulate JSON somehow manually
  // for example replace some images or change text

  // then we can convert json into image
  const imageBase64 = await instance.jsonToImageBase64(json); // default is PNG
  // write image into local file
  fs.writeFileSync('out.png', imageBase64, 'base64');

  // also we can export design into lower size
  // and change image type
  const jpegImage = await instance.jsonToImageBase64(json, {
    pixelRatio: 0.5, // make image twice smaller
    mimeType: 'image/jpeg',
  });
  fs.writeFileSync('out.jpg', jpegImage, 'base64');

  // enable rich text rendering if your design uses it
  const richTextImage = await instance.jsonToImageBase64(json, {
    richTextEnabled: true, // enable rich text support
  });
  fs.writeFileSync('out-rich.png', richTextImage, 'base64');

  // close instance
  instance.close();
}

run();
```

## Error Handling [#error-handling]

Rendering failures inside the headless browser — broken images, missing fonts, invalid designs — are re-thrown on the Node side as plain `Error`s with a `code` (e.g. `IMAGE_FAILED`, `FONT_FAILED`, `DESIGN_INVALID`) and structured `details` such as `elementId`. Branch on the code, not the message text — see [Error Handling](/docs/error-handling).

## Related Pages [#related-pages]

* [Cloud Render API](/docs/cloud-render-api) - Managed rendering service without infrastructure
* [Import and Export](/docs/import-and-export) - Overview of all export formats
* [Store API](/docs/store) - Complete API reference
* [JSON Schema](/docs/schema) - Structure reference for design JSON


---

# SVG Import
URL: https://polotno.com/docs/svg-import





The `@polotno/svg-import` package converts SVG files into Polotno JSON format, enabling you to import vector designs into Polotno for further editing.

<Callout type="warn">
  **Beta Feature:** This library is new and may not work correctly for all SVG files. Please [report issues](https://community.polotno.com/c/ask) to help us improve it.
</Callout>

<Callout type="info">
  **Try it without code:** The [SVG to JSON](/tools/svg-to-json) and [SVG to PDF](/tools/svg-to-pdf) converters run this exact parser in the browser — drop your own file to test it before integrating.
</Callout>

**Importing other formats?** See [PDF Import](/docs/pdf-import) and [PSD Import](/docs/psd-import) for the equivalent packages.

## Installation [#installation]

```bash
npm install @polotno/svg-import
```

## Basic Usage [#basic-usage]

```typescript
import { svgToJson } from '@polotno/svg-import';

const svg = `<svg viewBox="0 0 800 600">
  <text x="100" y="100" font-size="24">Hello World</text>
  <rect x="200" y="200" width="100" height="100" fill="blue"/>
</svg>`;

const json = await svgToJson({ svg });

// Load into Polotno store
store.loadJSON(json);
```

## Recommended Workflow [#recommended-workflow]

A common use case is importing designs from other design tools:

1. **Export from your design tool** — Export your design as SVG from any vector editor (e.g., Figma, Canva, Adobe Illustrator)
2. **Load the SVG file** — Read the SVG content in your application
3. **Convert to Polotno JSON** — Use `svgToJson()` to convert
4. **Load into Polotno** — Use `store.loadJSON()` to load the converted design

```typescript
import { svgToJson } from '@polotno/svg-import';

// Example: loading from file input
async function handleFileUpload(file: File) {
  const svgContent = await file.text();
  const json = await svgToJson({ svg: svgContent });
  store.loadJSON(json);
}

// Example: loading from URL
async function importFromUrl(url: string) {
  const response = await fetch(url);
  const svgContent = await response.text();
  const json = await svgToJson({ svg: svgContent });
  store.loadJSON(json);
}
```

`svgToJson` returns a complete, valid [Design Format](/docs/schema) document, ready for `store.loadJSON()`. See the reference for every field and type.

## Text Conversion Limitations [#text-conversion-limitations]

<Callout type="info">
  Some design tools (especially Canva and Illustrator) convert text into SVG paths when exporting. These **outlined texts cannot be converted back into editable text** — they will be imported as image data instead.
</Callout>

**To preserve editable text:**

* **Figma:*&#x2A; Use "Export" with SVG format and make sure **"Outline Text" is OFF** in export options. See the [Figma Import guide](/docs/figma-import) for detailed steps.
* **Illustrator:** Avoid "Create Outlines" before export, or use "Preserve Illustrator Editing Capabilities"
* **Canva:** Limited control — some fonts are automatically outlined

If editable text is critical, check your export settings or consider recreating text elements manually in Polotno after import.

## Platform Support [#platform-support]

<Callout type="warn">
  This package is designed for **client-side (browser) use only**. It may not work correctly in pure Node.js environments.
</Callout>

For server-side SVG processing, consider pre-processing on the client or using a headless browser environment.

## Demo [#demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-svg-import" />

## Error Handling [#error-handling]

If the input is not valid SVG, the importer throws a plain `Error` with `code: 'IMPORT_FAILED'` and `details.format: 'svg'`. See [Error Handling](/docs/error-handling).

## Troubleshooting [#troubleshooting]

**Import produces unexpected results:**

* Simplify the SVG before importing (flatten groups, expand strokes)
* Check if text was converted to paths in the source application
* Try exporting with different settings from your design tool

**Missing elements:**

* Some advanced SVG features may not be supported
* Check browser console for warnings

**Need help?** Report issues and get support at [community.polotno.com](https://community.polotno.com/c/ask).


---

# Video Export
URL: https://polotno.com/docs/video-export



## Overview [#overview]

Polotno supports exporting animated designs to video (MP4) format using **client-side rendering**. This means all video encoding happens directly in the browser without requiring a server. This feature is available through the `@polotno/video-export` package.

For server-side video generation at scale, see [Cloud Render API](/docs/cloud-render-api).

## Installation [#installation]

First, install the video export package:

```bash
npm install @polotno/video-export
```

## Basic Usage [#basic-usage]

Import the package and use the `storeToVideo` function to export your design:

```ts
import { storeToVideo } from '@polotno/video-export';
import { createStore } from 'polotno/model/store';

const store = createStore({ key: 'YOUR_KEY' });

// Export video
const videoBlob = await storeToVideo({
  store,
  fps: 30, // Frames per second (default: 30)
  pixelRatio: 2, // Pixel ratio for quality (default: 1)
  onProgress: (progress, frameTime) => {
    console.log(`Progress: ${Math.round(progress * 100)}%`);
    console.log(`Frame render time: ${frameTime}ms`);
  },
});

// Download the video
const url = URL.createObjectURL(videoBlob);
const link = document.createElement('a');
link.href = url;
link.download = 'video.mp4';
link.click();
```

## API Reference [#api-reference]

### `storeToVideo(options)` [#storetovideooptions]

Exports a Polotno design to video format.

**Parameters:**

* `store` (required): The Polotno store instance
* `fps` (optional): Frames per second for the video (default: `30`)
* `pixelRatio` (optional): Pixel ratio for quality control (default: `1`)
* `onProgress` (optional): Callback function for progress tracking
  * `progress`: Number between 0 and 1 representing export progress
  * `frameTime`: Time in milliseconds to render the current frame
* `includeAudio` (optional): Include audio tracks from the design in the exported video
* `signal` (optional): An `AbortSignal` to cancel video generation. When aborted, `storeToVideo` rejects with an `AbortError`.

**Returns:** Promise that resolves to a Blob containing the video file

### Cancelling an Export [#cancelling-an-export]

Use an `AbortController` to cancel a long-running export:

```ts
const controller = new AbortController();

// Cancel after 10 seconds
setTimeout(() => controller.abort(), 10_000);

try {
  const videoBlob = await storeToVideo({
    store,
    signal: controller.signal,
  });
} catch (err) {
  if (err.name === 'AbortError') {
    console.log('Export was cancelled');
  }
}
```

## Use Cases [#use-cases]

* Create video content from animated designs
* Export presentations as video files
* Generate social media videos
* Create video templates with animations
* Export multi-page designs as video sequences

## Notes [#notes]

<Callout type="info" title="Client-Side Rendering">
  All video encoding happens **directly in the browser** using client-side rendering. This means:

  * No server required for video processing
  * All processing happens on the user's device
  * Export speed depends on the user's hardware capabilities
  * Large videos or high FPS may take longer to process
</Callout>

## Multi-Page Designs with Different Dimensions [#multi-page-designs-with-different-dimensions]

Video files require a single fixed resolution throughout playback. When your store contains pages with different dimensions, `storeToVideo` determines the output resolution by taking the **maximum width and height** across all pages (rounded to even numbers for H.264 codec compatibility).

During export, all pages are temporarily resized to match this output resolution. The resize is smart — it preserves relative positions and sizes of elements, so the layout is mostly maintained. Original page dimensions are restored after the export completes.

<Callout type="info" title="Recommendation">
  For best results, use pages with **similar dimensions**. If your store mixes very different aspect ratios (e.g. a landscape page and a portrait page), the resized layout may not look as intended.
</Callout>

## Error Handling [#error-handling]

Export failures throw a plain `Error` with a `code` (`VIDEO_FAILED`, `FETCH_FAILED`, `EXPORT_FAILED`) and structured `details` — `details.reason` distinguishes cases like `no-video-track`, `unsupported-codec`, or `zero-duration`. Branch on the code, not the message text — see [Error Handling](/docs/error-handling).

## Common Questions [#common-questions]

### How long does video export take? [#how-long-does-video-export-take]

Export time depends on video length, complexity, and user hardware. Higher FPS and pixel ratios increase render time.

### Can I export videos server-side? [#can-i-export-videos-server-side]

Yes. Use the [Cloud Render API](/docs/cloud-render-api) for server-side video generation with consistent performance.

### Does this work with animations? [#does-this-work-with-animations]

Yes. Enable animations first with `setAnimationsEnabled(true)`. See [Animations and Videos](/docs/animations-and-videos) for details.

## Live Demo [#live-demo]

Try out the video export feature in this interactive demo:

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-video-export" />


---

# Angular
URL: https://polotno.com/docs/angular



## How to integrate Polotno editor into an Angular app? [#how-to-integrate-polotno-editor-into-an-angular-app]

Polotno is a React-based editor. You can embed it inside an Angular application by rendering a small React component into an Angular host element.

### 1) Install dependencies [#1-install-dependencies]

```bash
npm install react react-dom polotno
```

Optionally, install MobX bindings for Angular to react to Polotno store changes from Angular templates:

```bash
npm install mobx-angular
```

### 2) Create the Polotno Editor as a React component [#2-create-the-polotno-editor-as-a-react-component]

Create `polotno/editor.tsx` and bootstrap the editor. Replace `YOUR_API_KEY` with your actual key from the Polotno cabinet.

```tsx
// polotno/editor.tsx
import React from 'react';
import { PolotnoContainer, SidePanelWrap, WorkspaceWrap } from 'polotno';
import { Toolbar } from 'polotno/toolbar/toolbar';
import { ZoomButtons } from 'polotno/toolbar/zoom-buttons';
import { SidePanel } from 'polotno/side-panel';
import { Workspace } from 'polotno/canvas/workspace';
import { createStore } from 'polotno/model/store';

// Polotno UI styles
import 'polotno/ui.css';

export const store = createStore({
  key: 'YOUR_API_KEY',
  showCredit: true,
});
store.addPage();

export const App = () => {
  return (
    <PolotnoContainer style={{ height: '90vh' }}>
      <SidePanelWrap>
        <SidePanel store={store} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} />
        <Workspace store={store} />
        <ZoomButtons store={store} />
      </WorkspaceWrap>
    </PolotnoContainer>
  );
};
```

### 3) Mount the React editor from an Angular component [#3-mount-the-react-editor-from-an-angular-component]

Use Angular lifecycle hooks to create and unmount a React root. Expose the Polotno `store` to the template if you want to show reactive data.

```ts
// app.component.ts
import { Component, OnDestroy, AfterViewInit } from '@angular/core';
import * as ReactDOM from 'react-dom/client';
import * as React from 'react';
import { App as ReactEditor, store } from './polotno/editor';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  standalone: true,
})
export class AppComponent implements AfterViewInit, OnDestroy {
  root: ReactDOM.Root | undefined;
  store = store; // make store available in template

  ngAfterViewInit() {
    const container = document.getElementById('editor')!;
    this.root = ReactDOM.createRoot(container);
    this.renderComponent();
  }

  private renderComponent() {
    this.root!.render(React.createElement(ReactEditor));
  }

  ngOnDestroy() {
    this.root?.unmount();
  }
}
```

Make sure the component template has a container for the editor:

```html
<!-- app.component.html -->
<div id="editor"></div>
```

### 4) (Optional) Setup MobX reactions [#4-optional-setup-mobx-reactions]

The `mobx-angular` library can automatically bind Polotno store updates to Angular templates. Add the module to your component (or app module) and use `*mobxAutorun`.

```ts
// app.component.ts (standalone component example)
import { Component } from '@angular/core';
import { MobxAngularModule } from 'mobx-angular';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  standalone: true,
  imports: [MobxAngularModule],
})
export class AppComponent {}
```

```html
<!-- app.component.html -->
<div *mobxAutorun class="header">
  Number of pages: {{ store.pages.length }}
  <button (click)="store.addPage()">Add page</button>
  <!-- the React editor mounts below -->
  <div id="editor"></div>
  
</div>
```

### Customization [#customization]

From `polotno/editor.tsx` you can customize panels, toolbar, and canvas. From Angular, interact with the exported `store` to load a design, modify pages/elements, and export results (images/PDF). See other guides in this section for theming and configuration.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-angular" />


---

# Build with AI
URL: https://polotno.com/docs/build-with-ai



Polotno ships official tooling for AI coding assistants: **skills** that teach your agent the SDK, an **MCP server** for live documentation search, and **machine-readable docs**. Set these up before writing code — your assistant will know Polotno's APIs, patterns, and pitfalls instead of guessing.

## Install skills [#install-skills]

Skills are lightweight instruction packs your agent loads on demand. Polotno provides two in the [polotno-project/skills](https://github.com/polotno-project/skills) repository:

* **polotno-sdk** — SDK development assistant: core API patterns, a capability map of everything the SDK provides, and live documentation lookup.
* **polotno-design** — headless design generation: produce a Polotno JSON design from a text brief, render it to PNG/PDF, and bulk-generate variants from data.

### Claude Code [#claude-code]

Installs both skills plus the documentation MCP server:

```bash
claude plugin marketplace add polotno-project/skills
claude plugin install polotno@polotno
```

Or from within a Claude Code session:

```
/plugin marketplace add polotno-project/skills
/plugin install polotno@polotno
```

### Cursor, Copilot, Codex, Windsurf, Cline, and others [#cursor-copilot-codex-windsurf-cline-and-others]

```bash
npx skills add polotno-project/skills
```

The [skills CLI](https://github.com/vercel-labs/skills) auto-detects which agents you have and installs the skills in each one's native format.

### Manual setup [#manual-setup]

Copy the skill content from the repo into your agent's instructions file — `skills/polotno-sdk/SKILL.md` (with its `capabilities.md`) for SDK development:

| Platform       | File                              |
| -------------- | --------------------------------- |
| Cursor         | `.cursorrules`                    |
| GitHub Copilot | `.github/copilot-instructions.md` |
| Codex / Jules  | `AGENTS.md`                       |
| Windsurf       | `.windsurfrules`                  |

## Live documentation search (MCP) [#live-documentation-search-mcp]

The Polotno skills are designed to look up API details in the live docs rather than carry stale copies. The Claude Code plugin above already includes the MCP server. For any other MCP-capable agent, add it to your MCP config:

```json
{
  "mcpServers": {
    "polotno-documentation": {
      "command": "npx",
      "args": [
        "crawl-chat-mcp",
        "--id=67e312247a822a2303f2b8a7",
        "--name=polotno_documentation"
      ]
    }
  }
}
```

The server uses stdio transport and indexes both the documentation and the [community forum](https://community.polotno.com/home). Works with Cursor, Cline, and any MCP-compatible editor. Requires Node.js 18+.

The same search powers the AI assistant widget on this docs site and on the community forum — ask questions like "How do I resize a page?" for instant cited answers.

## Machine-readable docs [#machine-readable-docs]

* **Markdown version of any docs page** — append `.md` to the URL, e.g. [`/docs/store.md`](https://polotno.com/docs/store.md). Clean markdown, no navigation or scripts.
* [llms.txt](https://polotno.com/llms.txt) — an LLM-oriented index of Polotno: core concepts, product pages, and documentation links.
* [llms-full.txt](https://polotno.com/llms-full.txt) — the complete documentation as a single markdown document, for agents that want everything in one request.
* [AI info page](https://polotno.com/ai-info-page) — a condensed product brief for AI assistants.

## Alternatives [#alternatives]

[Context7](https://context7.com) also serves up-to-date Polotno documentation via MCP:

```bash
npx ctx7 setup
```

Use flags to target a specific editor: `--cursor`, `--claude`, `--opencode`. A free API key from [context7.com/dashboard](https://context7.com/dashboard) is recommended for higher rate limits.

## What you can ask [#what-you-can-ask]

Once set up, your assistant can answer with sources:

* **API questions** – "What properties does TextElement have?"
* **Code examples** – "How to add a rounded rectangle?"
* **Troubleshooting** – "Why isn't my custom font loading?"


---

# Removing "Powered by Polotno"
URL: https://polotno.com/docs/credit



## Requirements [#requirements]

**Trial keys always show the "Powered by Polotno" credit.** This branding cannot be removed with trial keys, regardless of configuration.

To remove the credit, you must have a **paid license**.

## How to Remove [#how-to-remove]

Follow all three steps:

### 1. Purchase a Paid License [#1-purchase-a-paid-license]

Get a paid license from your [Polotno dashboard](https://polotno.com/login). Trial keys will not work.

### 2. Register Your Domain [#2-register-your-domain]

Add your domain in your [Polotno dashboard](https://polotno.com/login). The API key validates against registered domains.

**Important:** Register the exact domain including subdomain (e.g., `app.example.com` vs `example.com`).

### 3. Use the Correct API Key and Configuration [#3-use-the-correct-api-key-and-configuration]

This is **critical**. You must use the API key from your paid license and set `showCredit: false`:

```ts
import { createStore } from 'polotno/model/store';

const store = createStore({
  key: 'YOUR_API_KEY', // Must be from your paid license, not a trial key
  showCredit: false,
});
```

For frameworkless integrations:

```ts
import { createDemoApp } from 'polotno/polotno-app';

const { store } = createDemoApp({
  container: document.getElementById('root'),
  key: 'YOUR_API_KEY',
  showCredit: false,
});
```

## Troubleshooting [#troubleshooting]

If the credit still appears:

* **Verify your API key** - Confirm you're using the key from your paid license (check in your [Polotno dashboard](https://polotno.com/login))
* **Check domain registration** - Ensure your exact domain is listed in the dashboard
* **Confirm `showCredit: false`** - Make sure it's explicitly set in your configuration
* **Clear cache** - Hard refresh your browser (Cmd+Shift+R or Ctrl+Shift+R)

The most common issue is using a trial API key instead of a paid license key.


---

# Customizations
URL: https://polotno.com/docs/customizations





First, let's talk about the user interface.

The Polotno editor has several main components:

<img alt="Polotno Editor Components" src="__img0" />

## Full Control of the Side Panel [#full-control-of-the-side-panel]

You have complete control over the Side Panel. You can remove the default panels, add your own, and customize their content entirely. For instance, you can create a panel that loads images directly from your backend. Check out the [Side Panel Overview](/docs/side-panel-overview) for more information.

## Toolbar, Page Controls, and Tooltip Customization [#toolbar-page-controls-and-tooltip-customization]

You can modify, remove, or add controls and buttons in the [Toolbar](/docs/toolbar), [Page Controls](/docs/workspace), and [Tooltip](/docs/tooltip), allowing you to tailor the interface to your needs.

## Timeline Customization [#timeline-customization]

Currently, the **Timeline** component is not customizable. However, you can remove it and implement your own version using the [Store API](/docs/store).

## Canvas Customization [#canvas-customization]

The Canvas component offers several style customization options. You can modify properties like background color and selection tool colors. For more options, refer to the [Workspace Documentation](/docs/workspace).

## General Style Customization [#general-style-customization]

You can also use [CSS to overwrite](/docs/theme-and-ui-styles) and customize the general styles of the editor.

## Data Loading and Export [#data-loading-and-export]

You have full control over how data is loaded into the editor, saved, and exported.

For example:

* Load custom templates or a specific user's design from your backend.
* Save a JSON file to a local computer with a button click.
* Automatically send requests to your backend with design data on any changes.
* Upload design previews or exports to an S3 bucket.

The [Store API](/docs/store) allows you to implement all of these features, ensuring your data flow fits seamlessly with your infrastructure.

## Building custom UI with `polotno/primitives` [#building-custom-ui-with-polotnoprimitives]

When you add your own panels, toolbar buttons, or dialogs, you can build them with the same components the editor uses, so they match the default UI out of the box. They're exposed at `polotno/primitives`.

```tsx
import { Button, Input, Select, Popover, Tooltip, Slider, Tabs } from 'polotno/primitives';

const MyPanel = () => (
  <div>
    <Input placeholder="Search…" />
    <Button onClick={() => {}}>Add</Button>
  </div>
);
```

Available primitives include `Button`, `Input`, `Textarea`, `Select`, `Popover`, `Tooltip`, `Slider`, `Tabs`, `Dialog`, `Switch`, `NumericInput`, and more. They follow the editor's theme, including [dark mode](/docs/theme-and-ui-styles).

## Overriding icons [#overriding-icons]

You can swap any editor icon (or a whole pack) by semantic name with `setIcons`. See [Editor Configuration → How to override icons?](/docs/editor-configuration#how-to-override-icons).


---

# Editor configuration
URL: https://polotno.com/docs/editor-configuration



## How to change image upload behavior? [#how-to-change-image-upload-behavior]

The default [Side Panel](/docs/side-panel-overview) has an Upload tab to import local images into the project. The same upload function also handles images and files pasted from the clipboard onto the canvas. By default, Polotno converts a local file into a Base64 string. These strings are then used by `image` elements. Using Base64 may produce large project JSON because images are fully encoded inside it.

**It is highly recommended to upload images to your server.** This will keep [JSON](/docs/import-and-export) smaller, easier to read, and significantly improve the canvas editor performance.

If you want to upload local images to your server, use:

```ts
import { setUploadFunc } from 'polotno/config';

// define your upload function (implement your API logic here)
async function upload(localFile: File) {
  const formData = new FormData();
  formData.append('files[]', localFile);
  const res = await fetch(yourServerURL, {
    method: 'POST',
    body: formData,
  });
  const json = await res.json();
  const { url } = json;
  // return a simple and short URL
  return url as string;
}

// set new function
setUploadFunc(upload);
```

Similar to image uploads, you can customize font uploading behavior in the Text panel:

```ts
import { setFontUploadFunc } from 'polotno/config';

// define your upload function (implement your API logic here)
async function upload(localFile: File) {
  const formData = new FormData();
  formData.append('files[]', localFile);
  const res = await fetch(yourServerURL, {
    method: 'POST',
    body: formData,
  });
  const json = await res.json();
  const { url } = json;
  // return a simple and short URL
  return url as string;
}

// set new function
setFontUploadFunc(upload);
```

## How to translate UI? [#how-to-translate-ui]

If you would like to translate the UI into a different language or change some labels, use:

```ts
import { setTranslations } from 'polotno/config';

setTranslations(
  {
    sidePanel: {
      text: 'Текст',
      myFonts: 'Мои шрифты',
    },
  },
  {
    validate: true, // set to false if you don't need validation
  }
);
```

To inspect the full translation schema:

```ts
import { getTranslations } from 'polotno/config';

// log full translations object
console.log(getTranslations());
```

You can also use the same translation API to translate your custom components:

```tsx
import { observer } from 'mobx-react-lite';
import { t } from 'polotno/utils/l10n';

// in your component
const App = observer(() => {
  return <div>{t('sidePanel.yourLabel')}</div>; // sidePanel.yourLabel is a key in translations object
});
```

If you are working on a translation for any language or changing default labels, please share your results—it helps us improve defaults and provide ready-to-use translations.

## How to override icons? [#how-to-override-icons]

You can replace any editor icon (or a whole pack) by semantic name with `setIcons`. It mirrors the localization pattern: it shallow-merges by key, so call it repeatedly to override more icons, or pass a whole set to restyle the editor. Pass any React component that forwards `className`.

```tsx
import { setIcons } from 'polotno/config';
import { MyBoldIcon, MyItalicIcon } from './my-icons';

setIcons({
  bold: MyBoldIcon,
  italic: MyItalicIcon,
});
```

## How to configure fonts? [#how-to-configure-fonts]

See the dedicated [Fonts guide](/docs/fonts) for comprehensive documentation on:

* Google Fonts configuration
* Design fonts (per-design custom fonts stored in JSON)
* Global fonts (app-wide fonts not stored in JSON)
* Font upload customization

## Change default preset colors in color picker [#change-default-preset-colors-in-color-picker]

By default, the color picker generates preset colors from (1) used colors in the design and (2) default colors. You can override this logic with your own presets:

```ts
import { setColorsPresetFunc } from 'polotno/config';

// define your own function
setColorsPresetFunc((store) => {
  // return array of colors
  return ['#000', '#fff'];
});
```


---

# Frameworkless Integration
URL: https://polotno.com/docs/frameworkless-integration



**Polotno** is optimized for integration with the React framework.

However, for scenarios requiring no customization, a “frameworkless” version of Polotno is available. This version can be easily included on a page with simple script tags.

```html
<!-- add styles -->
<link href="https://unpkg.com/polotno@4/ui.css" rel="stylesheet" />

<!-- add polotno bundle -->
<!-- (!) important: make sure it is added into body of document (not <head>) -->
<script src="https://unpkg.com/polotno@4/polotno.bundle.js"></script>

<!-- set styles for the editor -->
<style>
  body {
    padding: 0;
    margin: 0;
  }
  #container {
    width: 100vw;
    height: 100vh;
  }
  /* optionally enable dark theme */
  /* body.dark { background: #1e1e1e; } */
  /* <body class="dark"> */
</style>

<!-- create container for editor -->
<div id="container"></div>

<!-- init the editor -->
<script>
  const { store } = createPolotnoApp({
    // this is a demo key just for that project
    // (!) please don't use it in your projects
    // to create your own API key please go here: https://polotno.com/cabinet
    key: 'nFA5H9elEytDyPyvKL7T',
    // you can hide back-link on a paid license
    // but it will be good if you can keep it for Polotno project support
    showCredit: true,
    container: document.getElementById('container'),
    // also optionally you can specify which side panels you want to show
    // by default all panels are shown
    // sections: ['photos', 'text', 'elements', 'upload', 'background', 'layers']
  });

  // you can use full store API available here: /docs/store
  // for any configurations you can use window.polotnoConfig object
  // it gives you full configs available in: import { something } from 'polotno/config'
  window.polotnoConfig.setAnimationsEnabled(true);
</script>
```


---

# iOS Swift
URL: https://polotno.com/docs/ios-swift



## How to integrate Polotno editor into an iOS app? [#how-to-integrate-polotno-editor-into-an-ios-app]

Polotno is a React-based web editor. You can embed it into a native iOS Swift application by bundling the editor as a single-file web app and loading it in a `WKWebView`. This hybrid approach lets you leverage Polotno's full web capabilities while maintaining a native iOS experience.

## Architecture overview [#architecture-overview]

The integration uses a hybrid architecture:

* **Native Layer**: SwiftUI app with `WKWebView` to host the editor
* **Web Layer**: React + Vite app that runs Polotno editor
* **Communication**: JavaScript bridge via `WKScriptMessageHandler` for bidirectional data exchange

The web editor is built as a single-file bundle (using `vite-plugin-singlefile`) to avoid module loading issues when loading from local files in `WKWebView`.

## Prerequisites [#prerequisites]

* Xcode 15+ (iOS 16+ deployment target)
* Node.js 18+ and npm (for building the web editor)

## Integration approach [#integration-approach]

The integration involves two main parts:

1. **Web editor**: Create a React + Vite app with Polotno, configured to build as a single-file bundle using `vite-plugin-singlefile`. This generates one HTML file with all JavaScript and CSS inlined.

2. **Swift wrapper**: Create a `WKWebView` wrapper in Swift that loads the bundled HTML file and handles bidirectional communication via `WKScriptMessageHandler`.

The web editor exposes global functions (e.g., `window.__polotnoReceiveInitialDoc`, `window.saveToNative`) that Swift can call. The editor posts messages back to Swift using `window.webkit.messageHandlers.editor.postMessage()`.

See the [demo repository](https://github.com/polotno-project/polotno-swift) for complete implementation details.

## Core concepts [#core-concepts]

### Single-file bundle [#single-file-bundle]

The editor must be built as a single HTML file with all JavaScript and CSS inlined. This prevents:

* Module loading errors from local file restrictions
* Cross-origin issues with separate asset files
* Network dependency during initial load

Use `vite-plugin-singlefile` to achieve this.

### Message passing [#message-passing]

Communication between Swift and JavaScript uses `WKScriptMessageHandler`:

* **Swift → JavaScript**: Use `webView.evaluateJavaScript()` to call global functions
* **JavaScript → Swift**: Use `window.webkit.messageHandlers.editor.postMessage()` to send data

### Data serialization [#data-serialization]

Design data is passed as JSON strings, base64-encoded for safe transmission. Preview images are base64-encoded PNG data URLs.

## FAQ [#faq]

### Can the editor work offline? [#can-the-editor-work-offline]

The editor code is bundled locally, but Polotno relies on external APIs for stock photos, templates, and fonts. The device must be online for these features.

**Enterprise clients**: Full offline support (bundling all assets and fonts) is available with enterprise licenses. Contact support for details.

### What are the memory considerations? [#what-are-the-memory-considerations]

High-resolution exports or complex designs may consume significant memory. Test on older devices (iPhone 8, iPad Air 2) if targeting a broad user base. Consider:

* Limiting export resolution for previews
* Using lower pixel ratios for preview generation
* Implementing memory warnings and cleanup
* Rendering on the server side

### How do I customize the editor UI? [#how-do-i-customize-the-editor-ui]

Modify the React component in `web-editor/src/App.jsx`:

* Add custom side panels
* Modify toolbar actions
* Change default sections
* Add custom save flows

### Can I export to PDF or other formats? [#can-i-export-to-pdf-or-other-formats]

Yes. Extend the JavaScript bridge to support additional export formats. Use `store.toPDF()` or other export methods, convert the result to base64, and post it to Swift via the message handler.

### How do I handle errors? [#how-do-i-handle-errors]

Implement error handling in both layers:

* **JavaScript**: Wrap Polotno API calls in try-catch blocks
* **Swift**: Validate message payloads and handle decoding errors gracefully

## Demo repository [#demo-repository]

See a complete working example with source code: [https://github.com/polotno-project/polotno-swift](https://github.com/polotno-project/polotno-swift)

The repository includes:

* Complete Xcode project
* React + Vite web editor setup
* SwiftUI integration example
* Build scripts for bundling


---

# Next.js
URL: https://polotno.com/docs/next-js



## How to use Polotno Design editor with Next.js? [#how-to-use-polotno-design-editor-with-nextjs]

Demo repository: [polotno-next](https://github.com/polotno-project/polotno-next)

### 1) Install dependencies [#1-install-dependencies]

```bash
## Next.js 15 or 16 (React 19):
npm install polotno

## Next.js 14 (React 18):
npm install polotno@next-react18
```

The default 4.x line targets React 19 (Next.js 15/16). The 3.x line for React 18 (Next.js 14) is legacy and available for now — see [React Version Support](/docs/react-19-support).

### 2) Create an Editor component (client-only) [#2-create-an-editor-component-client-only]

Create `components/editor.tsx`. Do not place it inside `pages` or `app` to avoid server-side rendering.

```tsx
import React from 'react';
import { PolotnoContainer, SidePanelWrap, WorkspaceWrap } from 'polotno';
import { Toolbar } from 'polotno/toolbar/toolbar';
import { PagesTimeline } from 'polotno/pages-timeline';
import { ZoomButtons } from 'polotno/toolbar/zoom-buttons';
import { SidePanel } from 'polotno/side-panel';
import { Workspace } from 'polotno/canvas/workspace';
import 'polotno/ui.css';
import { createStore } from 'polotno/model/store';

const store = createStore({
  key: 'YOUR_API_KEY', // create an API key at https://polotno.com/cabinet/
  // you can hide back-link on a paid license
  // but it will be good if you can keep it for Polotno project support
  showCredit: true,
});
store.addPage();

export const Editor = () => {
  return (
    <PolotnoContainer style={{ width: '100vw', height: '100vh' }}>
      <SidePanelWrap>
        <SidePanel store={store} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} downloadButtonEnabled />
        <Workspace store={store} />
        <ZoomButtons store={store} />
        <PagesTimeline store={store} />
      </WorkspaceWrap>
    </PolotnoContainer>
  );
};

export default Editor;
```

### 3) Use dynamic import in a client component [#3-use-dynamic-import-in-a-client-component]

```tsx
'use client';

import dynamic from 'next/dynamic';
const Editor = dynamic(() => import('../components/editor'), {
  ssr: false,
});

export default function Home() {
  return <Editor />;
}
```

## Disable ReactStrictMode in Next.js 15 or 16 [#disable-reactstrictmode-in-nextjs-15-or-16]

Disable ReactStrictMode in your `next.config.js` file:

```js
module.exports = {
  reactStrictMode: false,
};
```

At the current moment Polotno does not support ReactStrictMode in Next.js 15 or 16. It is a known issue and we are working on it.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-nextjs" />


---

# Non-React integration
URL: https://polotno.com/docs/non-react-integration



**Polotno** is designed for use with the React framework, requiring a React environment for customization. However, you can still integrate Polotno with other frameworks, such as Vue, Angular, and Svelte. Here is how:

1. Start by creating an isolated project for the editor component.
2. Use Polotno to build and customize the editor as needed.
3. Develop a set of API methods to facilitate communication with the primary project.
4. Compile the project into basic source files, eliminating the need for JSX or transpilers.
5. Incorporate the compiled bundle into the main project.

It is important to note that React proficiency remains essential for customizing the Polotno editor. For demonstration purposes, this guide uses the Parcel bundler.

* Example repository: [polotno-non-react-integration](https://github.com/polotno-project/polotno-docs/tree/main/examples/polotno-non-react-integration)
* Parcel: [parceljs.org](https://parceljs.org/)

### 1. Installations [#1-installations]

First install Parcel, Polotno and React:

```bash
npm install parcel polotno react react-dom
```

### 2. Create project [#2-create-project]

Create a new folder for the editor inside your project root, for example `editor`:

```bash
mkdir editor
```

### 3. Create index.html [#3-create-indexhtml]

Create `editor/index.html`. It will be a template for your editor during isolated development.

Note: this HTML file is not used by your main app; it is only for local development of the editor bundle.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />

    <link href="https://unpkg.com/polotno@4/ui.css" rel="stylesheet" />
    <style>
      body {
        padding: 0;
        margin: 0;
      }
      #root {
        width: 100vw;
        height: 100%;
      }
    </style>
  </head>

  <body>
    <div id="root"></div>
    <script src="./index.js" type="module"></script>
    <script>
      window.onload = () => {
        window.createEditor({ container: document.getElementById('root') });
      };
    </script>
  </body>
  </html>
```

### 4. Create index.js [#4-create-indexjs]

Create `editor/index.js`. It is the main entry point for your editor.

```js
import React from 'react';
import ReactDOM from 'react-dom/client';
import { PolotnoContainer, SidePanelWrap, WorkspaceWrap } from 'polotno';
import { Toolbar } from 'polotno/toolbar/toolbar';
import { ZoomButtons } from 'polotno/toolbar/zoom-buttons';
import { SidePanel } from 'polotno/side-panel';
import { Workspace } from 'polotno/canvas/workspace';

import { createStore } from 'polotno/model/store';

const store = createStore({
  key: 'nFA5H9elEytDyPyvKL7T', // you can create it here: https://polotno.com/cabinet/
  // you can hide back-link on a paid license
  // but it will be good if you can keep it for Polotno project support
  showCredit: true,
});
const page = store.addPage();

export const App = ({ store }) => {
  return (
    <PolotnoContainer style={{ width: '100vw', height: '100vh' }}>
      <SidePanelWrap>
        <SidePanel store={store} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} />
        <Workspace store={store} />
        <ZoomButtons store={store} />
      </WorkspaceWrap>
    </PolotnoContainer>
  );
};

// default API of your editor
export const createEditor = ({ container }) => {
  const root = ReactDOM.createRoot(container);
  root.render(<App store={store} />);
};

// make API global for simple start in development
window.createEditor = createEditor;
```

### 5. Start development server [#5-start-development-server]

```bash
parcel ./editor/index.html
```

Tip: you can also add this command to your `package.json`:

```json
{
  "scripts": {
    "dev": "parcel ./editor/index.html"
  }
}
```

### 6. Open editor in browser [#6-open-editor-in-browser]

Open `http://localhost:1234` in your browser. That URL is default for Parcel, but it may use a different port—check your terminal output.

### 7. Compile editor [#7-compile-editor]

First tell Parcel where to put the compiled code. Add this line to your `package.json`:

```json
{
  "main": "editor.js"
}
```

When you are happy with your editor, compile it into plain JS files:

```bash
parcel build ./editor/index.js --no-source-maps
```

You can also add a build script to `package.json`:

```json
{
  "scripts": {
    "build:editor": "parcel build ./editor/index.js --no-source-maps"
  }
}
```

### 8. Use editor in your project [#8-use-editor-in-your-project]

Now you can use your editor in your project. Add the generated `editor.js` file into your app and import its API:

```js
import { createEditor } from './editor.js';

// somewhere in your code
createEditor({ container: document.getElementById('editor') });
```

Remember to include the Polotno UI styles in your host app:

```html
<link href="https://unpkg.com/polotno@4/ui.css" rel="stylesheet" />
```

### 9. API [#9-api]

The `createEditor` method shown here is just a simple example. You can extend it with methods to communicate with your main project, pass initial data, and define callbacks.

### Vue example [#vue-example]

[Open Vite + Vue + Polotno example](https://codesandbox.io/s/github/polotno-project/polotno-docs/tree/main/examples/polotno-and-vue-custom?file=/src/components/Editor.vue)

### 10. Pitfalls [#10-pitfalls]

Installing all editor dependencies may conflict with your main project. If that happens, move the whole editor workflow into its own `package.json` inside the `editor` folder and install dependencies there.


---

# Overview
URL: https://polotno.com/docs/overview



**Polotno** is an opinionated JavaScript library and set of React components designed to create canvas editors tailored for various business applications. The SDK provides a complete visual editor framework for building white-label design tools, template systems, and programmatic image generation.

There are many powerful JavaScript frameworks and tools that can help you make a canvas editor. But almost all of them are 'low-level' in nature. Take [Konva.js](https://konvajs.org/) for example – it's a great 2d canvas framework; but you'd need to write **a lot of code** to make a full canvas editor app.

Polotno is a simple tool that solves a focused set of business problems. It is fast and we are committed to keeping the API as light as possible. So you can just drop it on the page and get a full featured design suite.

<Callout type="note">
  **Using an AI coding assistant?** Install the official [Polotno skills and docs MCP server](/docs/build-with-ai) for Claude Code, Cursor, Codex, and other agents first — your assistant will know the SDK before you write a line of code.
</Callout>

## Quick Start (React) [#quick-start-react]

### 1. Install polotno package [#1-install-polotno-package]

```bash
npm install polotno
```

This installs the default **4.x** line, which targets **React 19**. Still on React 18? A legacy 3.x line is available for now — see [React Version Support](/docs/react-19-support).

### 2. Create Editor component [#2-create-editor-component]

```tsx
import React from 'react';
import { PolotnoContainer, SidePanelWrap, WorkspaceWrap } from 'polotno';
import { Toolbar } from 'polotno/toolbar/toolbar';
import { PagesTimeline } from 'polotno/pages-timeline';
import { ZoomButtons } from 'polotno/toolbar/zoom-buttons';
import { SidePanel } from 'polotno/side-panel';
import { Workspace } from 'polotno/canvas/workspace';

import 'polotno/ui.css';

import { createStore } from 'polotno/model/store';

const store = createStore({
  key: 'YOUR_API_KEY', // you can create it here: https://polotno.com/cabinet/
  // you can hide back-link on a paid license
  // but it will be good if you can keep it for Polotno project support
  showCredit: true,
});
const page = store.addPage();

export const Editor = () => {
  return (
    <PolotnoContainer style={{ width: '100vw', height: '100vh' }}>
      <SidePanelWrap>
        <SidePanel store={store} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} downloadButtonEnabled />
        <Workspace store={store} />
        <ZoomButtons store={store} />
        <PagesTimeline store={store} />
      </WorkspaceWrap>
    </PolotnoContainer>
  );
};
```

### 3. Use the component in your app [#3-use-the-component-in-your-app]

```tsx
import { Editor } from './editor';

const App = () => {
  return <Editor />
}
```

## Quick Start (No Frameworks) [#quick-start-no-frameworks]

```javascript
import { createDemoApp } from 'polotno/polotno-app';

// import Polotno UI styles
// if your bundler doesn't support such an import, you can use the CSS from a CDN (see below)
import 'polotno/ui.css';

const { store } = createDemoApp({
  container: document.getElementById('root'),
  key: 'YOUR_API_KEY', // you can create it here: https://polotno.com/cabinet/
  // you can hide back-link on a paid license
  // but it will be good if you can keep it for Polotno project support
  showCredit: true,
});
```

Optionally, you can import CSS styles from CDN:

```html
<link href="https://unpkg.com/polotno@4/ui.css" rel="stylesheet" />
```

## Core Concepts [#core-concepts]

### Store [#store]

The [Store](/docs/store) is the main object to control data and elements of the canvas. It provides API for adding/updating/removing canvas objects, undo/redo, selection changes, zooming, and [export/import operations](/docs/import-and-export).

```javascript
import { createStore } from 'polotno/model/store';

const store = createStore();
const page = store.addPage();

page.addElement({
  x: 50,
  y: 50,
  type: 'text',
  fill: 'black',
  text: 'hello',
});
```

### Workspace React Canvas Component [#workspace-react-canvas-component]

React component for drawing canvas app on the page; comes with basic functionality for common edits: selection, resize, actual drawing of objects, snapping, etc.

```tsx
import Workspace from 'polotno/canvas/workspace';

const App = () => {
  return <Workspace store={store} />;
};
```

### UI Components [#ui-components]

Set of React components for general canvas editor app.

* a toolbar for basic objects manipulations actions (such as align, remove, change objects styles, etc)
* side panels for adding new objects
* zooming buttons
* etc

```tsx
import { PolotnoContainer, SidePanelWrap, WorkspaceWrap } from 'polotno';
import { Toolbar } from 'polotno/toolbar/toolbar';
import { ZoomButtons } from 'polotno/toolbar/zoom-buttons';
import { SidePanel } from 'polotno/side-panel';
import { Workspace } from 'polotno/canvas/workspace';

export const App = ({ store }) => {
  return (
    <PolotnoContainer style={{ width: '100vw', height: '100vh' }}>
      <SidePanelWrap>
        <SidePanel store={store} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} downloadButtonEnabled />
        <Workspace store={store} />
        <ZoomButtons store={store} />
      </WorkspaceWrap>
    </PolotnoContainer>
  );
};
```

### Styles [#styles]

The default Polotno UI is built on its own design system. Import its styles once with `import 'polotno/ui.css'`. If you build your own custom UI or additional components, you can reuse Polotno's building blocks from [`polotno/primitives`](/docs/customizations) so they match the editor, or use any style framework you prefer.

### Reactivity [#reactivity]

The core of Polotno is built using the [MobX](https://mobx.js.org/) library. You can leverage MobX API to add reactivity to your own application. The foundation of Polotno is built with the [MobX](https://mobx.js.org/) library. To incorporate reactivity into your application, you can utilize the MobX API along with the [mobx-state-tree](https://mobx-state-tree.js.org/intro/welcome) library. Within the React framework, the `observer()` function is essential.

```tsx
import { observer } from 'mobx-react-lite';

const App = observer(({ store }) => {
  return (
    <div>
      <p>Here we will define our own custom tab.</p>
      <p>Elements on the current page: {store.activePage?.children.length}</p>
    </div>
  );
});
```


---

# Polotno 4 Migration
URL: https://polotno.com/docs/polotno-4-migration



Starting with Polotno &#x2A;*3.x (React 18)** and &#x2A;*4.x (React 19)**, the editor ships with a **new default UI** built on its own design system. The previous [Blueprint](https://blueprintjs.com/)-based chrome still ships under `polotno/blueprint/*`, so you can either adopt the new UI or keep the old look.

<Callout type="note">
  Pick your version line first: **4.x** targets React 19 (`npm i polotno`), **3.x** targets React 18 (`npm i polotno@next-react18`). See [React Version Support](/docs/react-19-support).
</Callout>

## Path A — Adopt the new UI (recommended) [#path-a--adopt-the-new-ui-recommended]

The component API is unchanged, so this is mostly a CSS swap.

### 1. Swap the CSS import [#1-swap-the-css-import]

```js
// Before
import '@blueprintjs/core/lib/css/blueprint.css';

// After
import 'polotno/ui.css';
```

### 2. Imports stay the same [#2-imports-stay-the-same]

The default `Toolbar`, `SidePanel`, `PagesTimeline`, and `Workspace` are already the new UI — your imports don't change:

```tsx
import { Toolbar } from 'polotno/toolbar/toolbar';
import { SidePanel } from 'polotno/side-panel';
import { PagesTimeline } from 'polotno/pages-timeline';
import { Workspace } from 'polotno/canvas/workspace';
```

### 3. Update dark mode [#3-update-dark-mode]

Dark mode moved to the `dark` class (see [Theme](/docs/theme-and-ui-styles)):

```html
<body class="dark"></body>
```

### 4. Custom UI [#4-custom-ui]

If you built custom panels, toolbar buttons, or dialogs, rebuild them with [`polotno/primitives`](/docs/customizations) so they match the new design system.

## Path B — Keep the Blueprint UI [#path-b--keep-the-blueprint-ui]

If you're not ready to change the look, import the editor chrome from `polotno/blueprint/*`.

### 1. Install Blueprint v6 [#1-install-blueprint-v6]

The Blueprint chrome relies on Blueprint v6 as a peer dependency (`@blueprintjs/select` is now required), so install all three packages — the same ones your own Blueprint components use:

```bash
npm i @blueprintjs/core@6 @blueprintjs/icons@6 @blueprintjs/select@6
```

### 2. Import the chrome from `blueprint/*` [#2-import-the-chrome-from-blueprint]

`Workspace`, `model/store`, `config`, and `utils/*` stay on their normal paths — only the toolbar, side panel, and timeline change.

```js
// Before
import { Toolbar } from 'polotno/toolbar/toolbar';
import { SidePanel } from 'polotno/side-panel';
import { ImagesGrid } from 'polotno/side-panel/images-grid';
import { PagesTimeline } from 'polotno/pages-timeline';

// After
import { Toolbar } from 'polotno/blueprint/toolbar';
import { SidePanel, ImagesGrid } from 'polotno/blueprint/side-panel';
import { PagesTimeline } from 'polotno/blueprint/pages-timeline';
```

### 3. CSS [#3-css]

`polotno/blueprint.css` bundles the Blueprint base styles and the Polotno chrome in one file.

```js
// Before
import '@blueprintjs/core/lib/css/blueprint.css';
// After
import 'polotno/blueprint.css';
```

### 4. Dark mode → `bp6-dark` [#4-dark-mode--bp6-dark]

The Blueprint chrome is on Blueprint v6, which renamed its CSS prefix from `bp5-` to `bp6-`. Update any hardcoded class strings in your CSS, JSX `className`s, and `index.html` — including the dark-mode class:

```html
<body class="bp6-dark"></body>
<!-- was bp5-dark -->
```

This is **not** a build error — the theme just silently stops applying. (`Classes.*` constants from `@blueprintjs/core` resolve automatically; only hardcoded `bp5-` strings need changing.)

<Callout type="note">
  The `<Workspace>` canvas overlays (page controls, tooltip) and the zoom buttons use the new UI — Blueprint-styled variants of those aren't exposed as separate imports in this version, so keep `Workspace` and `ZoomButtons` on their default paths.
</Callout>

The Blueprint chrome is deprecated and will be removed in a future release. When you're ready, drop it and rebuild custom UI with [`polotno/primitives`](/docs/customizations).


---

# Polotno Button
URL: https://polotno.com/docs/polotno-button



**Polotno Button** is a dedicated script that enables easy and efficient embedding of the Polotno Editor to any website. With just a simple button, you can give your app a new dimension of customization for any design.

## Why Use Polotno Button? [#why-use-polotno-button]

There are several key reasons why implementing a Polotno button can significantly benefit your website and business.

1. **User-Friendly Designing:** Online design tools, such as Polotno, push the boundaries of creativity with a precise and user-friendly UI, enabling even non-professionals to create compelling designs. By incorporating the Polotno button into your application, you give your users the tools they need to go beyond traditional design boundaries.
2. **Seamless Integration:** The Polotno button can be seamlessly incorporated into your website without heavy coding or complex functionality.
3. **Save Time and Resources:** With the Polotno button, users can effortlessly craft designs right within your platform. This can reduce the need for external design platforms or software, thereby saving time and resources.
4. **Boost Engagement:** Providing users with the ability to create and customize designs can lead to increased user engagement on your platform.

## How to integrate Polotno Button? [#how-to-integrate-polotno-button]

1. Add the Polotno Button script to your website.

```html
<script src="https://embed.polotno.com/button-v1.js"></script>
```

2. Create a button somewhere on your page.

```html
<button id="polotno-button">Open Editor</button>
```

3. Initialize Polotno Button with your API key.

```html
<script>
const button = document.getElementById('polotno-button');
button.addEventListener('click', () => {
  window.createPolotnoEditor({
    key: 'my-api-key',
    onPublish: ({ dataURL, json }) => {
      // do something with generated image
      // also you can save json somewhere and load it later
    },
  });
});
</script>
```

## Polotno Button Options [#polotno-button-options]

The Polotno Button can be customized to fit your needs.

```javascript
function inchesToPx(inches) {
  var dpi = 72; // dots per inch
  return inches * dpi;
}

window.createPolotnoEditor({
  key: 'my-api-key',
  // select sections you want to show
  sections: [
    'templates',
    'photos',
    'text',
    'elements',
    'upload',
    'background',
    'layers',
    'size',
  ],
  defaultSection: 'photos', // what section open by default
  // initial size of the canvas
  width: inchesToPx(20),
  height: inchesToPx(10),
  // load template from json file
  jsonUrl:
    'https://api.polotno.com/templates/2021-10-25-instagram-post-sunday-reminder.json',
  // load template from json object
  json: {
    // json object of the design
  },
  // change default text of the publish button
  publishLabel: 'Save',
  onPublish: ({ dataURL, json }) => {
    document.getElementById('result').src = dataURL;
    console.log('json', json);
  },
  // optionally you can react to any change in the editor
  // for example temporary save design somewhere to restore it later via jsonUrl
  // you may need to save JSON manually to your server
  onChange: ({ json }) => {
    console.log('json', json);
  },
  // you can pass initial uploads to the editor
  // they will be shown in the upload section
  uploads: [
    {
      url: 'https://example.com/image.jpg',
      preview: 'https://example.com/image.jpg',
    },
  ],
  // you can enable or disable animations
  // by default animations are disabled
  // warning - editor can't export into video or gif yet
  // you have to use Cloud API or your own server for that
  animationsEnabled: true,

  // also you can translate full UI, ask us for the list of keys
  translations: {
    sidePanel: {
      templates: 'Шаблоны',
    },
  },
});
```


---

# Theme
URL: https://polotno.com/docs/theme-and-ui-styles



Styling Polotno Design Editor to match your design.

The default Polotno UI ships with its own design system. Load its styles once with `import 'polotno/ui.css'`. You can theme the editor in a few layers, from highest to lowest effort:

1. **Theme variables** — recolor the whole UI by setting a few CSS variables ([see below](#theming-with-css-variables)).
2. **Dark mode** — a single class toggle (below).
3. **Canvas chrome props** — recolor selection, guides, transformers, etc. via `<Workspace>` props ([see below](#theming-the-canvas-chrome)).
4. **CSS overrides** — target Polotno's stable `polotno-*` selectors for finer changes.

<Callout type="note">
  If you build custom UI, reuse the editor's own components from [`polotno/primitives`](/docs/customizations) so they stay consistent with the theme.
</Callout>

## Prebuilt themes [#prebuilt-themes]

Polotno ships ready-made themes as plain CSS files. Import one after `polotno/ui.css`:

```ts
import 'polotno/ui.css';
import 'polotno/themes/carbon.css'; // IBM Carbon look (IBM Plex fonts, light + dark)
// or
import 'polotno/themes/blueprint.css'; // classic Blueprint look of older Polotno versions
```

## Theming with CSS variables [#theming-with-css-variables]

The UI's colors, border radius, and font all come from CSS variables. Define them on `:root` (or any element that wraps the editor) to recolor it — you only need to set the ones you want to change; everything else keeps its default.

```css
:root {
  /* main accent (primary buttons, active states) */
  --primary: #6d28d9;
  --primary-foreground: #ffffff;

  /* base surface and text */
  --background: #ffffff;
  --foreground: #1a1a1a;

  /* corner roundness and UI font */
  --radius: 0.5rem;
  --font-sans: 'Inter', sans-serif;
}
```

Values accept any CSS color (hex, `rgb()`, `oklch()`, etc.). If your app already defines a theme with these variables, the editor matches it automatically — no extra setup.

### All variables [#all-variables]

Each color also has a `-foreground` pair (the text/icon color drawn on top of it) where relevant.

| Variable                                                                                                                                     | Controls                                     |
| -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `--background` / `--foreground`                                                                                                              | Base editor surface and default text         |
| `--card` / `--card-foreground`                                                                                                               | Raised surfaces — panels, cards              |
| `--popover` / `--popover-foreground`                                                                                                         | Popovers, dropdowns, menus                   |
| `--primary` / `--primary-foreground`                                                                                                         | Main accent — primary buttons, active states |
| `--secondary` / `--secondary-foreground`                                                                                                     | Secondary buttons and controls               |
| `--muted` / `--muted-foreground`                                                                                                             | Muted backgrounds and secondary text         |
| `--accent` / `--accent-foreground`                                                                                                           | Hover / selected highlight                   |
| `--destructive` / `--destructive-foreground`                                                                                                 | Delete and other dangerous actions           |
| `--border`                                                                                                                                   | Borders and dividers                         |
| `--input`                                                                                                                                    | Input field borders                          |
| `--ring`                                                                                                                                     | Focus ring                                   |
| `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-accent`, `--sidebar-border`, `--sidebar-ring` (and `-foreground` pairs) | The side-panel tab rail                      |
| `--chart-1` … `--chart-5`                                                                                                                    | Color palette for chart elements             |
| `--radius`                                                                                                                                   | Corner roundness of controls and surfaces    |
| `--font-sans`                                                                                                                                | UI font family                               |

To theme dark mode, set the variables under the `dark` class:

```css
.dark {
  --primary: #a78bfa;
  --background: #18181b;
  --foreground: #fafafa;
}
```

### Isolating the change to the editor [#isolating-the-change-to-the-editor]

The plain variables above are shared — setting `--primary` on `:root` also affects any of your own UI that reads it. To re-theme **only** the editor without touching the rest of your app, set the same names with a `--pn-` prefix instead. They take priority over the plain variables for Polotno, and your app keeps its own values.

```css
:root {
  --pn-primary: #6d28d9;
  --pn-background: #ffffff;
  --pn-radius: 0.5rem;
}
```

Every variable in the table has a `--pn-` counterpart (`--pn-primary`, `--pn-border`, `--pn-radius`, `--pn-font-sans`, …).

## How to enable dark theme? [#how-to-enable-dark-theme]

To enable dark mode, add the `dark` class to any editor container (for example, the `body`).

```html
<body class="dark">
  <div id="container"></div>
</body>
```

Alternatively, set `data-polotno-theme="dark"` directly on a Polotno container — useful when you can't add a `dark` class to an ancestor.

```html
<div data-polotno-theme="dark">
  <!-- editor -->
</div>
```

## How to change styles of side panel and toolbar? [#how-to-change-styles-of-side-panel-and-toolbar]

For finer changes, use CSS. Inspect the DOM to find class names. Polotno keeps a set of stable `polotno-*` selectors you can target (prefer these over utility classes, which can change between releases).

```css
/* overwrite colors for side-panel tabs */
.dark .polotno-side-tabs-container .polotno-side-panel-tab:hover,
.dark .polotno-side-tabs-container .polotno-side-panel-tab.active {
  background-color: #c8c52d;
  color: white;
}
```

## Live demo [#live-demo]

Pick a preset to recolor the editor live, toggle light/dark, and hit **Show code** to copy the CSS variables (with or without the `--pn-` prefix).

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-theme" />

## Theming the canvas chrome [#theming-the-canvas-chrome]

All editor canvas chrome — selection rectangles, transformer handles, snap guides, distance guides, crop overlays, loading/error indicators, rulers, and the hover highlighter — is themed via props on the `<Workspace>` component. Each prop is optional and merges with the default.

Example: recolor the editor accent away from the default blue.

```tsx
<Workspace
  store={store}
  selectionRectStroke="#c8c52d"
  selectionRectFill="rgba(200, 197, 45, 0.3)"
  snapGuideStroke="#c8c52d"
  transformLabelFill="#c8c52d"
  highlighterStyle={{ stroke: '#c8c52d' }}
/>
```

See the [Workspace](/docs/workspace) page for the full list of canvas styling props.

> The legacy `setTransformerStyle`, `setHighlighterStyle`, `setInnerImageCropTransformerStyle`, and `setOuterImageCropTransformerStyle` globals from `polotno/config` do the same thing globally and are deprecated — prefer the per-Workspace props.


---

# Vue.js
URL: https://polotno.com/docs/vue-js



## How to integrate Polotno editor into a Vue app? [#how-to-integrate-polotno-editor-into-a-vue-app]

Polotno is a React-based editor. You can embed it inside a Vue application by rendering a small React component into a Vue container.

### 1) Install dependencies [#1-install-dependencies]

```bash
npm install react react-dom polotno
```

Optionally, install MobX bindings for Vue to react to Polotno store changes in Vue templates:

```bash
npm install mobx-vue-lite
```

### 2) Create the Polotno Editor as a React component [#2-create-the-polotno-editor-as-a-react-component]

Create `components/editor.tsx` and bootstrap the editor. You can customize this file later (side panels, toolbar, etc.). Replace `YOUR_API_KEY` with your actual key from the Polotno cabinet.

```tsx
// components/editor.tsx
import React from 'react';
import { PolotnoContainer, SidePanelWrap, WorkspaceWrap } from 'polotno';
import { Toolbar } from 'polotno/toolbar/toolbar';
import { ZoomButtons } from 'polotno/toolbar/zoom-buttons';
import { SidePanel } from 'polotno/side-panel';
import { Workspace } from 'polotno/canvas/workspace';
import { createStore } from 'polotno/model/store';

// Polotno UI styles
import 'polotno/ui.css';

export const store = createStore({
  key: 'YOUR_API_KEY',
  showCredit: true,
});
store.addPage();

export const App = () => {
  return (
    <PolotnoContainer style={{ height: '90vh' }}>
      <SidePanelWrap>
        <SidePanel store={store} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} />
        <Workspace store={store} />
        <ZoomButtons store={store} />
      </WorkspaceWrap>
    </PolotnoContainer>
  );
};
```

### 3) Mount the React editor from a Vue component [#3-mount-the-react-editor-from-a-vue-component]

In a Vue SFC (e.g., `App.vue`), render the React editor into a div. If you installed `mobx-vue-lite`, you can wrap your template with `Observer` to react to store updates.

```vue
<template>
  <Observer>
    <div class="header">
      <div>
        This header is controlled by Vue. Pages: {{ store.pages.length }}
      </div>
      <button @click="store.addPage()">Add page</button>
    </div>
    <div id="editor"></div>
  </Observer>
  <!-- If you didn't install mobx-vue-lite, remove <Observer> and </Observer> wrappers -->
  <!-- <div id="editor"></div> -->
  <!-- <div class="header">Pages: {{ store.pages.length }}</div> will not auto-react without Observer -->
.</template>

<script setup lang="ts">
import * as ReactDOM from 'react-dom/client';
import * as React from 'react';
import { App as ReactEditor, store } from './components/editor';
import { Observer } from 'mobx-vue-lite';
import { onMounted, onUnmounted } from 'vue';

let root: ReactDOM.Root | undefined;

onMounted(() => {
  const container = document.getElementById('editor')!;
  root = ReactDOM.createRoot(container);
  root.render(React.createElement(ReactEditor));
});

onUnmounted(() => {
  root?.unmount();
});

// expose store to the template
defineExpose({ store });
</script>
```

### 4) Customization [#4-customization]

From `components/editor.tsx` you can customize panels, toolbar, and canvas. From Vue, you can interact with the exported `store` to load a design, modify pages/elements, and export results (images/PDF). See other guides in this section for theming and configuration.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-vue" />


---

# Add Signature to the Canvas
URL: https://polotno.com/docs/add-signature-to-the-canvas



In **Polotno** you cannot draw directly on the canvas. But you can create your own custom UI for drawing operations, and then add the result to the canvas using `image` or `svg` elements.

In this demo, we create a custom side panel to add a signature to the document.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-signature" />


---

# Advanced Syncing Design Elements
URL: https://polotno.com/docs/advanced-syncing-design-elements



Sometimes you want multiple elements in your design to stay perfectly in sync. For example, repeating headers, labels, or dynamic fields (like `{pageNumber}`) that should update automatically across multiple pages or locations.

This guide explains how to implement real-time syncing between elements based on a shared `custom.syncId` property. When one element is edited or removed, all others with the same syncId will update or be deleted accordingly.

## Key Concepts & Tips [#key-concepts--tips]

1. **Assign a `custom.syncId`** to every element that should be linked.
2. Use **MobX reactions** to detect when editing starts and ends.
3. When editing ends, **propagate updated props** to all other synced elements.
4. Use a **throttled change handler** to avoid unnecessary sync calls.
5. When a synced element is deleted, **automatically remove all its peers**.

## Custom Metadata for Syncing [#custom-metadata-for-syncing]

In this guide, we use the `custom` property of Polotno elements to store metadata for syncing and variables replacement.

> The `custom` field is not used internally by Polotno. It’s reserved for your own purposes and is safe to use for attaching any extra information (like flags, references, or identifiers).

### 1. Syncing element properties by syncId [#1-syncing-element-properties-by-syncid]

This function scans the store for elements with the same syncId as the currently selected one. It then copies over all properties (except the id) from the source to the others.

```ts
function syncElements(store: any) {
  const syncElement = store.selectedElements.find((el: any) => el.custom?.syncId);
  if (!syncElement) return;

  store.find((item: any) => {
    if (item !== syncElement && item.custom?.syncId === syncElement.custom.syncId) {
      const props = { ...syncElement.toJSON() };
      delete props.id; // Never copy over unique IDs

      const currentProps = item.toJSON();
      Object.keys(props).forEach((key) => {
        const from = currentProps[key];
        const to = props[key];

        // Only update if values are different
        if (JSON.stringify(from) !== JSON.stringify(to)) {
          item.set({ [key]: to });
        }
      });
    }
  });
}
```

> Place this logic inside a reaction or a throttled change listener to keep synced elements updated after user edits.

### Handling Page Number Placeholders [#handling-page-number-placeholders]

Polotno does **not** update `{pageNumber}` automatically.

To support dynamic text like `Page {pageNumber}`, you need to explicitly store the template string and update it when needed.

The logic below shows how to:

* Save the original text into `custom.text` when editing ends.
* Use `custom.text` as a template to insert the correct page number.

#### 1. Track Editing and Store Template [#1-track-editing-and-store-template]

This function sets up a MobX reaction to watch when editing starts and ends.

When editing ends, it saves the current text into `custom.text`, which acts as a template for future updates.

```ts
// Watch for changes in edit mode and trigger sync when edit ends
const setupEditReaction = (store: any) => {
  let lastEditElement: any = null;

  reaction(
    () => store.find((item: any) => item._editModeEnabled === true),
    (editElement: any) => {
      if (editElement) {
        // Restore original template if available
        editElement.set({
          text: editElement.custom?.text || editElement.text,
        });
        lastEditElement = editElement;
      } else {
        // Save the current text as template
        if (lastEditElement) {
          lastEditElement.set({
            custom: {
              ...lastEditElement.custom,
              text: lastEditElement.text,
            },
          });
        }
        syncElements(store); // Also triggers page number update
      }
    }
  );
};
```

#### 2. Replace `{pageNumber}` with Real Value [#2-replace-pagenumber-with-real-value]

Call this function to replace `{pageNumber}` in the visible text using the current page index. It uses `custom.text` (if available) as the source of truth.

```ts
// Replace {pageNumber} in text elements with their actual page index
const updatePageNumber = (element: any) => {
  const store = element.store;
  const page = element.page;
  const index = store.pages.indexOf(page);
  const baseText = element.custom?.text || element.text;

  element.set({
    text: baseText.replaceAll('{pageNumber}', index + 1 as any),
  });
};
```

We can call `updatePageNumber` inside the `change` event to keep all in sync.

### Deleting all synced elements when one is removed [#deleting-all-synced-elements-when-one-is-removed]

This function ensures cleanup: if a user deletes one synced element, all others with the same `syncId` will also be deleted. This prevents orphaned elements that were meant to be linked.

```ts
// Observe element removals and notify callback
const onElementRemove = (store: any, callback: (el: any) => void) => {
  let lastIds: Record<string, any> = {};

  store.on(
    'change',
    throttle(() => {
      const newIds: Record<string, any> = {};
      store.find((item: any) => {
        newIds[item.id] = item;
      });

      Object.keys(lastIds).forEach((id) => {
        if (!newIds[id]) {
          callback(lastIds[id]);
        }
      });

      lastIds = newIds;
    })
  );
};

// Remove all elements with the same syncId as the deleted one
const setupSyncDeletion = (store: any) => {
  onElementRemove(store, (element) => {
    const syncId = element.custom?.syncId;
    if (!syncId) return;

    const idsToDelete: string[] = [];
    store.find((item: any) => {
      if (item.custom?.syncId === syncId) {
        idsToDelete.push(item.id);
      }
    });

    store.deleteElements(idsToDelete);
  });
};
```

## Cloning and Syncing Elements Across All Pages [#cloning-and-syncing-elements-across-all-pages]

You can add a custom button (e.g., inside your editor’s toolbar) to let users **duplicate an element across all pages** while keeping those copies in sync.

Each cloned element will receive the same `custom.syncId`, so changes to one will be automatically applied to the rest.

```tsx
const ApplyToAllPages = ({ store, element, elements }: any) => {
  return (
    <Button
      onClick={() => {
        elements.forEach((element: any) => {
          // First, remove existing synced copies (if any)
          if (element.custom?.syncId) {
            const idsToDelete: string[] = [];
            store.find((item: any) => {
              if (item.custom?.syncId === element.custom.syncId && item !== element) {
                idsToDelete.push(item.id);
              }
            });
            store.deleteElements(idsToDelete);
          }

          // Assign a new syncId
          const syncId = nanoid();
          element.set({
            custom: {
              ...element.custom,
              syncId,
            },
          });

          // Copy the element to every other page
          const props = { ...element.toJSON() };
          delete props.id;

          store.pages.forEach((page: any) => {
            if (page !== element.page) {
              page.addElement(props, { skipSelect: true });
            }
          });
        });
      }}
    >
      Apply to all pages
    </Button>
  );
};
```

Then add it into the toolbar:

```tsx
<Toolbar
  store={store}
  components={{
    TextApplyToAllPages: ApplyToAllPages,
    ImageApplyToAllPages: ApplyToAllPages,
    VideoApplyToAllPages: ApplyToAllPages,
    FigureApplyToAllPages: ApplyToAllPages,
    GifApplyToAllPages: ApplyToAllPages,
    LineApplyToAllPages: ApplyToAllPages,
  }}
/>
```

## Demo [#demo]

1. Select a text element on the canvas.
2. Click &#x2A;*“Apply to all pages”** to clone the element to every page. All copies will be linked.
3. Type `{pageNumber}` in the text. Each copy will show the correct page number.
4. Edit the element. All copies will update automatically.
5. Delete the element. All linked copies will also be removed.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-advanced-sync-elements" />


---

# AI Design Generation
URL: https://polotno.com/docs/ai-design



<Callout type="warn">
  This feature is experimental and is in active development. The API and its behavior may change as we refine the model. For any feedback, please write a direct message on the forum: [https://community.polotno.com/u/a13e0cdd](https://community.polotno.com/u/a13e0cdd)
</Callout>

Use the Polotno AI API to generate complete designs from text prompts. This demo shows how to build a custom side panel that integrates with the AI design generation endpoint.

## Features [#features]

* **Text prompt input** — describe the design you want
* **JSON design output** — the API returns a `{ design }` object with a complete Polotno JSON design

## How it works [#how-it-works]

1. User enters a design prompt in the custom AI Design side panel
2. The app sends a POST request to the Polotno AI API
3. The API returns a `{ design }` object, and the `design` value is loaded via `store.loadJSON(design)`

## API [#api]

The demo uses the AI design creation endpoint:

```
POST https://api.polotno.com/api/ai/design/create?KEY=<your-api-key>
```

The API accepts a `prompt` field and returns an object with a `design` field:

Request body:

```json
{
  "prompt": "A business card with blue gradient"
}
```

Response:

```json
{
  "design": {
    ...Polotno JSON design...
  }
}
```

Load the returned design with `store.loadJSON(data.design)`.

<Callout type="info">
  Each AI design generation request will be billed at **$0.20 per design**. During the experimental phase, the API is **free to use**.
</Callout>

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-ai-design" />


---

# Bar Codes
URL: https://polotno.com/docs/bar-codes



There are several tools that will help you display and change bar codes in Polotno Editor:

1. Using [JsBarcode](https://github.com/lindell/JsBarcode) (or a similar library), generate an SVG image of a bar code.
2. With an `svg` element, display the generated SVG image on the canvas.
3. Use the `custom` attribute of the `svg` shape to save any additional data. You can store the bar code data string for future reference.

*Instructions: try changing the content of a selected bar code. Try to deselect the element to create new bar codes.*

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-bar-codes" />


---

# Book Cover Editor
URL: https://polotno.com/docs/book-cover-editor



### How to make a book cover design editor? [#how-to-make-a-book-cover-design-editor]

The demo illustrates how to display a product preview using the export feature of Polotno.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-book-cover-editor" />


---

# Carousel in HTML Export
URL: https://polotno.com/docs/carousel-in-html-export



Polotno's HTML export is fully customizable via the `elementHook` callback. This demo shows how to transform image elements into animated carousels during export.

## Key Concepts [#key-concepts]

1. **Custom Properties**: Store carousel images and timing in `element.custom` object
2. **Element Hook**: Transform elements during export using `store.toHTML({ elementHook })`
3. **Virtual DOM**: Return modified DOM structure from the hook to change export output

The element hook receives `{ dom, element }` and returns a modified DOM structure. You can inject custom HTML, add JavaScript for interactivity, and alter element rendering completely.

## Example: Transform Image to Carousel [#example-transform-image-to-carousel]

```tsx
const html = await store.toHTML({
  elementHook: ({ dom, element }) => {
    // Check if element has carousel images
    if (element.custom?.images && Array.isArray(element.custom.images)) {
      // Remove original children
      dom.children = [];
      
      // Create carousel container with slides
      return {
        type: 'div',
        props: {
          class: 'polotno-carousel-container',
          'data-carousel': 'true',
          'data-timeout': element.custom.carouselTimeout || 3000,
          style: { ...dom.props.style, overflow: 'hidden' }
        },
        children: element.custom.images.map((src, i) => ({
          type: 'img',
          props: {
            src,
            class: 'carousel-slide',
            style: {
              position: 'absolute',
              width: '100%',
              height: '100%',
              display: i === 0 ? 'block' : 'none'
            }
          }
        }))
      };
    }
    return dom;
  }
});
```

The exported HTML includes carousel JavaScript that rotates images at the specified interval. A custom side panel lets users configure carousel images and timing before export.

## Live Demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-carousel-in-html" />


---

# Charts Rendering
URL: https://polotno.com/docs/charts-rendering



Showing line, bar, pie charts on the canvas.

There are several tools that will help you display and change charts in Polotno Editor:

1. Using an SVG library to generate an SVG image of a chart.
2. With the `svg` element you can show the generated SVG image on the canvas.
3. Use the `custom` attribute of the `svg` shape to save any additional data into the element. You can use it to store chart data for future reference.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-charts" />


---

# Dynamic Template Variables
URL: https://polotno.com/docs/dynamic-template-variables





Leverage the capabilities of the Polotno SDK to craft templates that incorporate dynamic variables. This feature is useful for generating a variety of similar designs that vary in text or imagery.

<img alt="Dynamic Variables" src="__img0" />

You have full flexibility to build your own template system and even UI for it if needed. The workflow is simple:

1. Create a design with some variables in it.
2. Export design as JSON.
3. Save this JSON to the database/backend.
4. When you need to create a new design or export it, load JSON from the database and replace variables with real data.
5. Load or export the generated JSON.

Every design in Polotno can be represented as JSON via `store.toJSON()` function. Now it is up to you to decide how to create variations of this JSON. Here are several examples.

## Simple text replacement [#simple-text-replacement]

As a part of your application convention you can use `{variable}` syntax to mark places where you want to replace text. Users of the editor may manually type this text or you can provide some UI for it.

```ts
store.activePage.addElement({
  type: 'text',
  // lets use name variable
  text: 'Hello {name}!',
});
```

When you want to generate a new design or export it, you can replace `{name}` with a real name. Here is a pseudo code for the backend:

```ts
const json = loadJSONFromDatabase();
const names = ['John', 'Mike', 'Anna'];
// do bulk export
for (const name of names) {
  // we need to replace {name} with real name
  // ideally you should loop over all text elements and replace text there
  // but we can do a simple string replace for this example
  const jsonString = JSON.stringify(json);
  const newJson = JSON.parse(jsonString.replace('{name}', name));
  // export newJson
  await convertJSONToImage(newJson);
}
```

## Image replacement [#image-replacement]

You can set up a similar workflow for images. To mark some images as variable you can use `custom` attribute of `image` element. It is a free-form object that you can use to store any data. You can make your own UI where users can change this data.

```ts
store.activePage.addElement({
  type: 'image',
  src: 'https://example.com/placeholder.png',
  custom: {
    // lets use avatar variable
    variable: 'avatar',
  },
});
```

Then on the backend you can replace `src` of this image with a real image URL based on information from the `custom` attribute.

```ts
// util function to handle deep traversal of json
const forEveryChild = (node: any, cb: (n: any) => void) => {
  if (node.children) {
    node.children.forEach((child: any) => {
      cb(child);
      forEveryChild(child, cb);
    });
  }
};

const json = loadJSONFromDatabase();
const avatars = [
  'https://example.com/avatar1.png',
  'https://example.com/avatar2.png',
];
// do bulk export
for (const avatar of avatars) {
  // find all avatar images in the json
  json.pages.forEach((page: any) => {
    forEveryChild(page, (child) => {
      if (child.type === 'image' && child.custom?.variable === 'avatar') {
        child.src = avatar;
      }
    });
  });
  // export json
  await convertJSONToImage(json);
}
```

The demo below shows how to replace text in the design. The demo specifies only one variable `{name}` but you can add more variables according to your application logic.

Click the "Preview" button to see how generation works.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-variables" />


---

# Full Canvas Editor
URL: https://polotno.com/docs/full-canvas-editor



This is the default starting point for integrating Polotno.

It mounts the core **Workspace** together with all standard UI blocks—side panel, toolbar (with download), zoom buttons and pages timeline—giving you a ready-to-ship editor in one component tree.

Copy the snippet, add your own API key, and you can:

* keep the layout as-is for a quick launch, or
* swap, hide, or extend any of the UI components while the canvas engine stays untouched.

```tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { PolotnoContainer, SidePanelWrap, WorkspaceWrap } from 'polotno';
import { Toolbar } from 'polotno/toolbar/toolbar';
import { PagesTimeline } from 'polotno/pages-timeline';
import { ZoomButtons } from 'polotno/toolbar/zoom-buttons';
import { SidePanel } from 'polotno/side-panel';
import { Workspace } from 'polotno/canvas/workspace';

import 'polotno/ui.css';

import { createStore } from 'polotno/model/store';

const store = createStore({
  key: 'nFA5H9elEytDyPyvKL7T', // you can create it here: https://polotno.com/cabinet/
  // you can hide back-link on a paid license
  // but it will be good if you can keep it for Polotno project support
  showCredit: true,
});
const page = store.addPage();

export const App = ({ store }) => {
  return (
    <PolotnoContainer style={{ width: '100vw', height: '100vh' }}>
      <SidePanelWrap>
        <SidePanel store={store} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} downloadButtonEnabled />
        <Workspace store={store} />
        <ZoomButtons store={store} />
        <PagesTimeline store={store} />
      </WorkspaceWrap>
    </PolotnoContainer>
  );
};

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App store={store} />);
```

Use this demo as your boilerplate and build up from here.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-demo" />


---

# Grid UI
URL: https://polotno.com/docs/grid-ui



**Polotno** doesn't offer built-in support for a grid API or UI directly. However, you can utilize Polotno's existing elements to construct a grid UI. Additionally, invisible elements can be placed on the canvas to facilitate snapping to specific positions.

Another approach is to overlay an `svg` element on the canvas to display a grid. This requires dynamically generating the `svg` content based on the desired grid size.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-grid" />


---

# Highlight headings with a banner
URL: https://polotno.com/docs/highlight-headings-with-a-full-width-banner-in-polotno



A client recently asked: “Can we drop a stripe behind a heading that always stretches the full width of the design? Even when the text moves or resizes?” The answer is yes, and it takes only a tiny helper component and one change listener.

## How it works [#how-it-works]

* **Button** – When a text element is selected, the **Background Fill** button toggles a custom flag on that element.

```tsx
const TextFullWidthBackground = observer(({ element }) => (
  <Button
    active={element.custom?.fullWidthBackground}
    minimal
    onClick={() => {
      element.set({
        custom: {
          ...element.custom,
          fullWidthBackground: !element.custom?.fullWidthBackground,
        },
      });
    }}
  >
    Background Fill
  </Button>
));
```

* **Listener** – A debounced `store.on('change')` handler checks every flagged text element, creates (or removes) a rectangle beneath it, and keeps the rectangle in sync with any edits.

```ts
const checkBackground = () => {
  // first make sure we remove unrelated backgrounds
  const idsToDelete: string[] = [];
  store.find((element) => {
    const attachedTo = element.custom?.attachedTo;
    if (!attachedTo) return;
    const el = store.getElementById(attachedTo);
    const noBack = !el?.custom?.fullWidthBackground;
    if (!el || noBack) {
      idsToDelete.push(element.id);
    }
  });
  store.deleteElements(idsToDelete);

  store.find((element) => {
    if (!element.custom?.fullWidthBackground) return;

    let backgroundEl = store.find((el) => el.custom?.attachedTo === element.id);
    if (!backgroundEl) {
      backgroundEl = element.page.addElement({
        type: 'figure',
        subType: 'rect',
        fill: 'grey',
        selectable: false,
        draggable: false,
        resizable: false,
        custom: { attachedTo: element.id },
      });
    }

    const elementIndex = element.parent.children.indexOf(element);
    const backgroundIndex = backgroundEl.parent.children.indexOf(backgroundEl);
    if (elementIndex !== backgroundIndex + 1) {
      backgroundEl.page.setElementZIndex(backgroundEl.id, elementIndex);
    }

    backgroundEl.set({
      x: 0,
      y: element.y,
      width: store.width,
      height: element.height,
    });
  });
};

let timeout: any = null;
const requestChange = () => {
  if (timeout) return;
  timeout = setTimeout(() => {
    checkBackground();
    timeout = null;
  }, 10);
};

store.on('change', () => {
  requestChange();
});
```

## Demo [#demo]

* Click “Background Fill” on a selected text element
* See how the background rectangle reacts to text changes

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-full-width-background-for-text" />


---

# Lightweight SVG Preview
URL: https://polotno.com/docs/lite-svg-render



## Use case [#use-case]

You need a small preview (e.g., in a templates list) for a json, but you don't want to mount an interactive Polotno editor in the DOM.

## Why store.toDataURL() fails head-less [#why-storetodataurl-fails-head-less]

`store.toDataURL()` is using mounted `<Workspace />` component for rendering. While it is perfect for high-quality export or preview generation of the current store, it is hard to use such an approach if you want to generate a preview of a design, that is not loaded inside the editor.

## Lightweight alternative: JSON ➜ SVG ➜ Data URL [#lightweight-alternative-json--svg--data-url]

Polotno ships a utility that walks the JSON tree and serializes it directly to SVG. While SVG render is in beta stage and may produce inconsistent result comparing to canvas rendering, it may still give ideal result for preview.

```tsx
import { jsonToSVG } from 'polotno/utils/to-svg';
import { svgToURL } from 'polotno/utils/svg';

// templateJSON is your saved Polotno design
async function getThumbnailURL(templateJSON) {
  const svgString = await jsonToSVG({ json: templateJSON });
  return svgToURL(svgString); // returns data:image/svg+xml;utf8,…
}

// Example React component
function TemplateThumb({ json }) {
  const [url, setUrl] = React.useState<string | null>(null);

  React.useEffect(() => {
    getThumbnailURL(json).then(setUrl);
  }, [json]);

  return url ? <img src={url} alt="preview" /> : '…';
}
```

## Demo [#demo]

Take a look into Variations side panel. You can click "Generate variations" to create many svg images using changed svg export of a design.

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-svg-preview" />


---

# One-click page rotation
URL: https://polotno.com/docs/one-click-page-rotation



Need to flip a design from portrait to landscape (or back) without redrawing everything? The snippet below adds a single **Rotate** button that swaps the canvas width/height and spins every element by 90° so the layout stays intact.

```tsx
const PageRotate = ({ store }) => (
  <Button
    onClick={() => {
      // 1. swap page dimensions
      const [oldW, oldH] = [store.width, store.height];
      const [newW, newH] = [oldH, oldW];
      const [cx, cy] = [oldW / 2, oldH / 2];
      store.setSize(newW, newH);

      // 2. move + rotate every element
      const [ncx, ncy] = [newW / 2, newH / 2];
      store.pages.forEach((page) => {
        page.children.forEach((el) => {
          const [dx, dy] = [el.x - cx, el.y - cy];
          const [rx, ry] = [-dy, dx]; // 90° rotation matrix
          el.set({
            x: ncx + rx,
            y: ncy + ry,
            rotation: (el.rotation || 0) + 90,
          });
        });
      });
    }}
  >
    Rotate
  </Button>
);
```

## How it works [#how-it-works]

* **Swap the canvas size.** `store.setSize(newW, newH)` turns portrait into landscape.
* **Translate each object to the old center, rotate it, then translate to the new center.** That keeps relative positions unchanged.
* **Add 90° to each element’s rotation** so arrows, text, etc. remain upright.

### When is this handy? [#when-is-this-handy]

* Quickly test both orientations of a social graphic.
* Offer users an instant “make it landscape” button in a print template.

Drop `PageRotate` into your toolbar:

```tsx
<Toolbar store={store} components={{ PageRotate }} />
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-rotate-page" />


---

# Page Name
URL: https://polotno.com/docs/page-name



Showing page name in page controls.

You can customize PageControls components to show the page name on top of the canvas. You can also add the ability to edit that name and save it to the store.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-page-name" />


---

# Page Numbers on Canvas
URL: https://polotno.com/docs/page-numbers-on-canvas



What if you want to automatically add page numbers to your document?

Usually most elements in the store are controlled by the user. But with Polotno you can create your own elements and fully control them programmatically. In this demo we add a special hook to show page numbers directly on the canvas.

Instructions: Check the number on the first page. Try to add/reorder/remove pages, and you will see page numbers updated automatically.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-page-numbers" />


---

# Print for T‑shirts
URL: https://polotno.com/docs/print-for-t-shirts



A lot of merch platforms need a simple, white‑label canvas where customers can drop graphics on a shirt, then download a print‑ready file. Polotno lets you ship that in a day. Below is the approach we used in the live demo.

For t‑shirt background, we use image elements like this:

```ts
frontPage.addElement({
  type: 'svg',
  src: '/front.svg',
  width: 2500,
  height: 2500,
  x: -750,
  y: -400,
  showInExport: false,
  selectable: false,
});
```

That way, the background image is not selectable and will be excluded from the final export.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-t-shirt" />


---

# Programmatic Transform
URL: https://polotno.com/docs/programmatic-transform



When building custom UI for Polotno, you may need to transform elements programmatically — changing position, size, or rotation through input fields or buttons rather than the canvas transformer.

While Polotno provides an on-canvas transformer that handles grouped and multi-selected elements automatically, there's no direct API to perform the same bulk operations programmatically. This guide shows how to implement your own transform logic.

## Understanding Polotno Limitations [#understanding-polotno-limitations]

Polotno groups don't have their own `x`, `y`, `width`, `height`, or `rotation` properties. A group is just a container — only its children have transform properties. When you transform a group on canvas, Polotno internally transforms each child element.

To replicate this behavior via API, you need to:

1. Extract all leaf elements (non-group children) from your selection
2. Calculate the combined bounding box
3. Apply transforms to each element individually

## Required Utilities [#required-utilities]

Polotno provides math utilities that make this easier:

```ts
import {
  getTotalClientRect,
  getCenter,
  rotateAroundPoint,
} from 'polotno/utils/math';
import { forEveryChild } from 'polotno/model/group-model';
```

* `getTotalClientRect(shapes)` — returns the axis-aligned bounding box of elements, accounting for rotation
* `getCenter(rect)` — returns the center point of a rectangle
* `rotateAroundPoint(shape, angleDelta, center)` — rotates a shape around a point
* `forEveryChild(group, callback)` — iterates through all children of a group (including nested)

> **Why use `getTotalClientRect` for the center?** A simple calculation like `x + width/2` only works for non-rotated elements. When an element is already rotated, its visual center shifts. `getTotalClientRect` returns the correct bounding box accounting for rotation, so `getCenter` gives you the true visual center.

## Extracting Shapes from Selection [#extracting-shapes-from-selection]

First, get all leaf elements from your selection, handling groups properly:

```ts
function getShapes(elements) {
  const shapes = [];
  elements.forEach((el) => {
    if (el.type === 'group') {
      forEveryChild(el, (child) => {
        if (child.type !== 'group') {
          shapes.push(child);
        }
      });
    } else {
      shapes.push(el);
    }
  });
  return shapes;
}

// Usage
const shapes = getShapes(store.selectedElements);
```

## Transforming a Single Element [#transforming-a-single-element]

For a single non-group element, you can set properties directly:

```ts
const element = store.selectedElements[0];

// Position
element.set({ x: 100, y: 200 });

// Size (with locked aspect ratio)
const ratio = element.height / element.width;
element.set({ width: 300, height: 300 * ratio });

// Rotation around center (use bounding box for correct center even when rotated)
const bbox = getTotalClientRect([element]);
const center = getCenter(bbox);
const targetRotation = 45;
const delta = targetRotation - (element.rotation || 0);
const newShape = rotateAroundPoint(
  {
    x: element.x,
    y: element.y,
    width: element.width,
    height: element.height,
    rotation: element.rotation || 0,
  },
  delta,
  center
);
element.set(newShape);
```

## Transforming Multiple Elements [#transforming-multiple-elements]

For multiple selected elements, calculate the bounding box and transform each element relative to it:

```ts
const shapes = getShapes(store.selectedElements);
const bbox = getTotalClientRect(shapes);

// Move all elements by delta
function moveElements(deltaX, deltaY) {
  shapes.forEach((shape) => {
    shape.set({ x: shape.x + deltaX, y: shape.y + deltaY });
  });
}

// Scale all elements proportionally from top-left
function scaleElements(newWidth) {
  const scale = newWidth / bbox.width;
  const originX = bbox.x;
  const originY = bbox.y;

  shapes.forEach((shape) => {
    shape.set({
      x: originX + (shape.x - originX) * scale,
      y: originY + (shape.y - originY) * scale,
      width: shape.width * scale,
      height: shape.height * scale,
    });
  });
}

// Rotate all elements around bounding box center
function rotateElements(angleDelta) {
  const center = getCenter(bbox);

  shapes.forEach((shape) => {
    const newShape = rotateAroundPoint(
      {
        x: shape.x,
        y: shape.y,
        width: shape.width,
        height: shape.height,
        rotation: shape.rotation || 0,
      },
      angleDelta,
      center
    );
    shape.set(newShape);
  });
}
```

## Transforming Groups [#transforming-groups]

Groups work the same as multiple selections — extract the children and transform them:

```ts
const group = store.selectedElements[0]; // assuming it's a group

const shapes = [];
forEveryChild(group, (child) => {
  if (child.type !== 'group') {
    shapes.push(child);
  }
});

const bbox = getTotalClientRect(shapes);
const center = getCenter(bbox);

// Rotate group children by 15 degrees
shapes.forEach((shape) => {
  const newShape = rotateAroundPoint(
    {
      x: shape.x,
      y: shape.y,
      width: shape.width,
      height: shape.height,
      rotation: shape.rotation || 0,
    },
    15, // angle delta
    center
  );
  shape.set(newShape);
});
```

## Handling Rotation State [#handling-rotation-state]

When building UI controls for rotation, you need to track the "current rotation" of a group or multi-selection. Since there's no single rotation value, use a local state that:

1. Initializes to the common rotation of all shapes (or 0 if mixed)
2. Resets when selection changes
3. Syncs when rotation changes externally (e.g., via canvas handles)

```ts
const [localRotation, setLocalRotation] = React.useState(0);
const prevSelectionRef = React.useRef(null);

// Reset on selection change
React.useEffect(() => {
  const selectionKey = elements.map((e) => e.id).join(',');
  if (selectionKey !== prevSelectionRef.current) {
    prevSelectionRef.current = selectionKey;
    // Initialize to current rotation
    const rotations = shapes.map((el) => el.rotation || 0);
    const allSame = rotations.every((r) => r === rotations[0]);
    setLocalRotation(allSame ? rotations[0] : 0);
  }
}, [elements]);
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-programmatic-transform" />


---

# QR Codes
URL: https://polotno.com/docs/qr-codes



QR code shapes are not a built-in feature of Polotno. But you can easily render them via `svg` elements. You can also use the `custom` property of an element to save additional information, such as QR code content for future reference.

You can use [`qrcode`](https://www.npmjs.com/package/qrcode) (or another similar library) to generate the content of a QR code.

The tutorial below helps you create an initial version that you can later modify to fit your needs.

## Step 1. Create a side section to generate and edit QR codes [#step-1-create-a-side-section-to-generate-and-edit-qr-codes]

In a separate file add this code:

```tsx
import React from 'react';
import { observer } from 'mobx-react-lite';
import { SectionTab } from 'polotno/side-panel';
import QRCode from 'qrcode';
import * as svg from 'polotno/utils/svg';
import ImQrcode from '@meronex/icons/im/ImQrcode';
import { Button, Input } from 'polotno/primitives';

// create svg image for QR code for input text
export async function getQR(text: string) {
  return new Promise<string>((resolve) => {
    QRCode.toString(
      text || 'no-data',
      {
        type: 'svg',
        color: {
          dark: '#00F', // Blue dots
          light: '#0000', // Transparent background
        },
      },
      (err, string) => {
        resolve(svg.svgToURL(string));
      }
    );
  });
}

// define the new custom section
export const QrSection = {
  name: 'qr',
  Tab: (props) => (
    <SectionTab name="Qr" {...props}>
      <ImQrcode />
    </SectionTab>
  ),
  // we need observer to update component automatically on any store changes
  Panel: observer(({ store }) => {
    const [val, setVal] = React.useState('');

    const el = store.selectedElements[0];
    const isQR = el?.name === 'qr';

    // if selection is changed we need to update input value
    React.useEffect(() => {
      if (el?.custom?.value) {
        setVal(el?.custom.value);
      }
    }, [isQR, el]);

    // update image src when we change input data
    React.useEffect(() => {
      if (isQR) {
        getQR(val).then((src) => {
          el.set({
            src,
            custom: {
              value: val,
            },
          });
        });
      }
    }, [el, val, isQR]);

    return (
      <div>
        {isQR && <p>Update select QR code:</p>}
        {!isQR && <p>Create new QR code:</p>}
        <Input
          onChange={(e: any) => {
            setVal(e.target.value);
          }}
          placeholder="Type qr code content"
          value={val}
          style={{ width: '100%' }}
        />
        <div
          style={{
            display: 'flex',
            justifyContent: 'space-between',
            paddingTop: '20px',
          }}
        >
          <Button
            style={{
              display: isQR ? '' : 'none',
            }}
            onClick={() => {
              store.selectElements([]);
              setVal('');
            }}
          >
            Cancel
          </Button>
          <Button
            style={{
              display: isQR ? 'none' : '',
            }}
            onClick={async () => {
              const src = await getQR(val);

              store.activePage.addElement({
                type: 'svg',
                name: 'qr',
                x: 50,
                y: 50,
                width: 200,
                height: 200,
                src,
                custom: {
                  value: val,
                },
              });
            }}
          >
            Add new QR code
          </Button>
        </div>
      </div>
    );
  }),
};
```

## Step 2. Add the created section into the Polotno side panel [#step-2-add-the-created-section-into-the-polotno-side-panel]

```tsx
import { SidePanel, DEFAULT_SECTIONS } from 'polotno/side-panel';
import { QrSection } from './qr-section'; // this file is created on step 1

// add a new custom section
const sections = [QrSection, ...DEFAULT_SECTIONS];

// then in render of side panel:
<SidePanel store={store} sections={sections} defaultSection="qr" />
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-qr-codes" />


---

# Real-time Collaboration with PartyKit
URL: https://polotno.com/docs/real-time-collaboration-with-partykit



Polotno’s SDK is single‑user by design, but because the document state lives in a MobX‑State‑Tree store you can stream patches and replay them elsewhere. That’s exactly what [PartyKit](https://www.partykit.io/) does in the demo below: every user who joins the same room sees edits appear in under a second.

Sample code: [https://github.com/polotno-project/polotno-partykit](https://github.com/polotno-project/polotno-partykit)

Demo page: [https://polotno-partykit.lavrton.partykit.dev/](https://polotno-partykit.lavrton.partykit.dev/)

## How it works [#how-it-works]

1. **Each client** joins a PartyKit room (example-room).
2. On first load it asks the room for the current state: `{ type: 'request-state' }`.
3. The first peer to answer sends back a full snapshot: `{ type: 'reset-state', state: … }`.
4. After that we only ship incremental MobX patches: `{ type: 'patch', patch: … }`.
5. Every receiver applies the patch with `applyPatch(store.pages, patch)` and the canvas updates instantly.

The tiny guard `ignorePathRef` prevents echo loops while a patch is replaying.

```ts
const socket = usePartySocket({
  room: 'example-room',
  onMessage(evt) {
    const event = JSON.parse(evt.data);
    if (event.type === 'patch') {
      console.log('patch received');
      ignorePathRef.current = true;
      applyPatch(store.pages, event.patch);
      ignorePathRef.current = false;
    }
    if (event.type === 'reset-state') {
      console.log('reset-state received');
      ignorePathRef.current = true;
      store.loadJSON(event.state);
      ignorePathRef.current = false;
    }
    if (event.type === 'request-state') {
      console.log('request-state received');
      socket.send(
        JSON.stringify({
          type: 'reset-state',
          state: store.toJSON(),
        })
      );
    }
  },
});

React.useEffect(() => {
  // ask for the current state
  socket.send(JSON.stringify({ type: 'request-state' }));

  // stream local edits
  onPatch(store.pages, (patch) => {
    if (ignorePathRef.current) return;
    socket.send(JSON.stringify({ type: 'patch', patch }));
  });
}, []);
```

***

### A few notes [#a-few-notes]

* **Not part of core SDK** – Polotno doesn’t ship server code or conflict resolution; we simply forward MobX patches.
* **Latency‑tolerant** – patches are small JSON objects, so even high‑latency networks feel snappy.
* **Conflict strategy** – the demo is last‑write‑wins. For richer docs you might add per‑element locks or OT/CRDT.


---

# Replace placeholder with user upload
URL: https://polotno.com/docs/replacing-a-placeholder-image-with-a-user-uploaded-image



Use this approach when you want to give users the ability to quickly replace a default placeholder image in their design with a custom photo. This is useful for flyers, posters, and other templates where large images can be swapped out.

### 1. Mark an Image as a Placeholder [#1-mark-an-image-as-a-placeholder]

```ts
const width = 600;
const height = 400;
// Add a placeholder image element
// you can make you own with your own text
// placehold.co is just an example, better to use your own image
store.activePage.addElement(
  {
    type: 'image',
    src: 'https://placehold.co/600x400?text=Click+to+add+image',
    x: (store.width - width) / 2,
    y: (store.height - height) / 2,
    width,
    height,
    // custom property to identify placeholder
    custom: {
      isPlaceholder: true,
    },
  },
  { skipSelect: true }
);
```

### 2. Detect When the Placeholder Is Selected [#2-detect-when-the-placeholder-is-selected]

Watch for changes in `store.selectedElements`. If a placeholder image is selected, show an “Upload Your Picture” button or open a file picker immediately.

### 3. Replace the Placeholder Image [#3-replace-the-placeholder-image]

Once a user selects an image file, set the element’s `src` to the URL of that file and clear out `custom.isPlaceholder`.

### Implementation Example [#implementation-example]

Below is a minimal React-based implementation. The key points are:

* A hidden file input used to pick images
* A MobX reaction or state check to detect when the user selects the placeholder
* Replacing the placeholder image with the uploaded file

```tsx
import React from 'react';
import { reaction } from 'mobx';
import { getImageSize, getCrop } from 'polotno/utils/image';

export function usePlaceholderSelection(store: any) {
  const fileInputRef = React.useRef<HTMLInputElement | null>(null);

  // react to selected elements
  React.useEffect(() => {
    // Dispose reaction when component unmounts
    const dispose = reaction(
      () => store.selectedElements,
      (selectedElements: any[]) => {
        // Check if at least one selected element is a placeholder
        const placeholder = selectedElements.find(
          (el) => el.custom?.isPlaceholder
        );
        if (placeholder) {
          // Trigger the hidden file input
          fileInputRef.current?.click();
        }
      }
    );
    return () => dispose();
  }, [store]);

  const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    const reader = new FileReader();
    reader.onload = async (loadEvent) => {
      // we will use dataURL to set the image
      // but it is recommended to upload image to the server first
      // for better performance and smaller JSON export
      const dataURL = loadEvent.target?.result as string;
      // Find the currently selected placeholder element
      const placeholder = store.selectedElements.find(
        (el: any) => el.custom?.isPlaceholder
      );
      if (!placeholder) return;

      // Get new image dimensions and calculate crop to fill placeholder (cover)
      const { width, height } = await getImageSize(dataURL);
      const crop = getCrop(placeholder, { width, height });

      placeholder.set({
        src: dataURL,
        ...crop,
        custom: { isPlaceholder: false },
      });
    };
    reader.readAsDataURL(file);
    // Reset the file input so selecting the same file triggers onChange again
    e.target.value = '';
  };

  // Return a hidden file input to be triggered by the reaction
  return (
    <input
      ref={fileInputRef}
      type="file"
      style={{ display: 'none' }}
      accept="image/*"
      onChange={handleFileChange}
    />
  );
}
```

### 3. Use the Hook in Your App [#3-use-the-hook-in-your-app]

```tsx
import React from 'react';
import { PolotnoContainer, SidePanelWrap, WorkspaceWrap } from 'polotno';
import { Toolbar } from 'polotno/toolbar/toolbar';
import { PagesTimeline } from 'polotno/pages-timeline';
import { ZoomButtons } from 'polotno/toolbar/zoom-buttons';
import { SidePanel } from 'polotno/side-panel';
import { Workspace } from 'polotno/canvas/workspace';

export const App = ({ store }: { store: any }) => {
  const fileInput = usePlaceholderSelection(store);

  return (
    <PolotnoContainer style={{ width: '100vw', height: '100vh' }}>
      <SidePanelWrap>
        <SidePanel store={store} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} downloadButtonEnabled />
        <Workspace store={store} />
        {fileInput}
        <ZoomButtons store={store} />
        <PagesTimeline store={store} />
      </WorkspaceWrap>
    </PolotnoContainer>
  );
};
```

### Optional: Control How New Images Fit [#optional-control-how-new-images-fit]

<Callout type="tip">
  If aspect ratios differ and you want predictable results, use `getImageSize` and `getCrop` from `polotno/utils/image`. `getCrop` gives a CSS-like **cover** behavior (fills the placeholder and may crop edges).
</Callout>

For a **contain** effect, resize the element itself using `scale = Math.min(boxW / imgW, boxH / imgH)` and center the result (keep `cropX = cropY = 0`).

```ts
import { getImageSize, getCrop } from 'polotno/utils/image';

// After you get the uploaded file as dataURL
const { width, height } = await getImageSize(dataURL);
const crop = getCrop(placeholder, { width, height });

placeholder.set({
  src: dataURL,
  ...crop,
  custom: { isPlaceholder: false },
});
```

### Alternative UI Approaches [#alternative-ui-approaches]

* **Manual Button**: Display a button in the [Toolbar](/docs/toolbar) or [Tooltip](/docs/tooltip) that opens the file dialog.
* **Side Panel Section**: Create a custom side panel tab that appears only when a placeholder is selected.

### Tips [#tips]

* Use `custom.isPlaceholder` or any custom property to mark replaceable images.
* `getCrop` provides "cover" behavior (fills the placeholder, may crop edges).
* Crop values (`cropX`, `cropY`, `cropWidth`, `cropHeight`) are normalized 0–1 values.
* For best results, upload images to a server first instead of using data URLs.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-select-image-placeholder" />


---

# Single-page view with arrow navigation
URL: https://polotno.com/docs/single-page-view-with-arrow-navigation



By default, Polotno shows a tall stack of pages that you scroll through vertically. For some products (pitch‑deck builder, kiosk app), you may want a cleaner workflow: keep one page in view and let the user flip with arrows.

Use the `renderOnlyActivePage` property on `<Workspace />`, and extend default page controls to show arrows for navigation:

```tsx
import { observer } from 'mobx-react-lite';
import { PageControls as DefaultPageControls } from 'polotno/canvas/page-controls';
import { Workspace } from 'polotno/canvas/workspace';

const PageControls = observer((props) => {
  const activeIndex = store.pages.indexOf(store.activePage);
  const canGoBack = activeIndex > 0;
  const canGoForward = activeIndex < store.pages.length - 1;
  const height = store.scale * props.page.computedHeight;

  return (
    <>
      <DefaultPageControls {...props} />
      <Button
        disabled={!canGoBack}
        style={{
          position: 'absolute',
          top: props.yPadding + height / 2 + 'px',
          left: 5 + 'px',
        }}
        onClick={() => {
          store.selectPage(store.pages[activeIndex - 1].id);
        }}
      >
        {'<'}
      </Button>
      <Button
        disabled={!canGoForward}
        style={{
          position: 'absolute',
          top: props.yPadding + height / 2 + 'px',
          right: 5 + 'px',
        }}
        onClick={() => {
          store.selectPage(store.pages[activeIndex + 1].id);
        }}
      >
        {'>'}
      </Button>
    </>
  );
});

// in render
<Workspace store={store} renderOnlyActivePage components={{ PageControls }} />
```

## Demo [#demo]

* Use arrow navigation near page content to switch between pages

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-pages-navigation" />


---

# Templates Library
URL: https://polotno.com/docs/templates-library



You can use Polotno tools and [side panel customization](/docs/side-panel-overview) to build your own template library with design presets.

In order to make a templates library you will need:

1. Create a design in the Polotno Editor
2. Use `store.toJSON()` to [export the design](/docs/import-and-export) as a `.json` file
3. (Optional) Use `store.saveAsImage()` to save a preview image of a design
4. Repeat steps 1–3 as many times as you need in order to make a library of templates
5. If you skipped step 3 you can use [Cloud Render API](/docs/cloud-render-api) to generate previews automatically
6. Make a server‑side API to access a list of templates
7. Create a [custom side panel](/docs/side-panel-overview) to display a list of templates from that API
8. Use `store.loadJSON()` to import design into canvas

## (1–4) Making designs library [#14-making-designs-library]

You will need to use Polotno editor to create designs. Importing designs from other software is not directly supported.

Note: if you need to import from SVG files, please [contact us](https://polotno.com/contact).

## (5) Generating previews [#5-generating-previews]

You can use the [Polotno Cloud API](/docs/cloud-render-api) to generate previews with your own backend language.

```ts
import fs from 'fs';
import path from 'path';
import { createInstance } from 'polotno-node';

// we will look for local directory for templates
const FOLDER_NAME = 'templates';

async function run() {
  // create working instance
  const instance = await createInstance({
    // this is a demo key just for that project
    // (!) please don't use it in your projects
    // to create your own API key please go here: https://polotno.com/cabinet
    key: 'nFA5H9elEytDyPyvKL7T',
  });

  // read all files in the directory
  const files = fs.readdirSync(FOLDER_NAME);
  for (const file of files) {
    // if it is not a json file - skip it
    if (!file.endsWith('.json')) continue;

    // load file
    const data = fs.readFileSync(path.join(FOLDER_NAME, file)).toString();
    const json = JSON.parse(data);

    // convert JSON into image preview
    const imageBase64 = await instance.run(async (json) => {
      store.loadJSON(json);
      await store.waitLoading();
      // set width of previews (we usually don't need original size)
      const maxWidth = 200;
      const scale = maxWidth / store.width;
      const url = await store.toDataURL({ pixelRatio: scale });
      return url.split('base64,')[1];
    }, json);

    // save images locally into the same folder
    fs.writeFileSync(
      path.join(FOLDER_NAME, file.split('.')[0] + '.png'),
      imageBase64,
      'base64'
    );
    console.log(`Finished ${FOLDER_NAME} ${file}`);
  }
  // close instance
  instance.close();
}

run();
```

## (6) Making backend API to load templates [#6-making-backend-api-to-load-templates]

This step is out of **Polotno** scope. You can use any backend stack you like. Most likely, you will need an API to get a list of available templates. For every design, you will have to share a public path to **json** file and **png** preview.

## (7 and 8) Displaying templates on side panel [#7-and-8-displaying-templates-on-side-panel]

As soon as you have a backend API to get a list of templates, you can use [Side Panel Customization](/docs/side-panel-overview) to display that list on the page. In the demo we will use `<ImagesGrid />` and the `useInfiniteAPI` hook ([docs](/docs/utils-api)). You don't have to use them in your app, but they can save time for this use case.

```tsx
import React from 'react';
import { observer } from 'mobx-react-lite';
import { useInfiniteAPI } from 'polotno/utils/use-api';

import { SectionTab } from 'polotno/side-panel';
import MdPhotoLibrary from '@meronex/icons/md/MdPhotoLibrary';

import { ImagesGrid } from 'polotno/side-panel/images-grid';

export const TemplatesPanel = observer(({ store }) => {
  // load data
  const { data, isLoading } = useInfiniteAPI({
    getAPI: ({ page }) => `templates/page${page}.json`,
  });

  return (
    <div style={{ height: '100%' }}>
      <ImagesGrid
        shadowEnabled={false}
        images={data?.map((d) => d.items).flat()}
        getPreview={(item) => `/templates/${item.preview}`}
        isLoading={isLoading}
        onSelect={async (item) => {
          // download selected json
          const req = await fetch(`/templates/${item.json}`);
          const json = await req.json();
          // inject it into store
          store.loadJSON(json);
        }}
        rowsNumber={1}
      />
    </div>
  );
});

// define the new custom section
export const TemplatesSection = {
  name: 'custom-templates',
  Tab: (props) => (
    <SectionTab name="Custom templates" {...props}>
      <MdPhotoLibrary />
    </SectionTab>
  ),
  // we need observer to update component automatically on any store changes
  Panel: TemplatesPanel,
};
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-templates-library" />


---

# AI Text
URL: https://polotno.com/docs/ai-text



Polotno ships with an optional AI assistant that helps users draft, expand, and rewrite text elements. The feature is opt-in and stays hidden until you enable it in your application configuration.

## Enable AI text tools [#enable-ai-text-tools]

```ts
import { setAiTextEnabled } from 'polotno/config';

setAiTextEnabled(true);
```

<Callout type="warn">
  AI tools are disabled by default. Call `setAiTextEnabled(true)` during app initialization to expose the AI actions in the text side panel and text toolbar.
</Callout>

## Requirements [#requirements]

* **Subscription**: Valid Polotno API key with AI text access.
* **Network**: Client devices must reach Polotno's API endpoint.
* **Compliance**: Review your legal obligations before allowing users to submit prompts and generated content.
* **Pricing**: Included in the Polotno subscription plan—no additional per-request fees.

## User experience [#user-experience]

After activation, selecting a text element reveals an **AI write** button in the floating toolbar and in the inline text tooltip. Clicking it opens preset prompts such as "Rewrite", "Shorten", or "Continue writing". Generated content updates the currently selected text element immediately, and users can continue editing the result like any other text.


---

# Animations and Videos
URL: https://polotno.com/docs/animations-and-videos



## How to enable animation support? [#how-to-enable-animation-support]

```ts
import { setAnimationsEnabled } from 'polotno/config';

setAnimationsEnabled(true);
```

When you enable animations, Polotno will add additional UI in the toolbar to change animation properties of the selected object, show a “Videos” side panel with a library of stock videos, and adapt the Pages component with scene preview.

## Group animations [#group-animations]

A group can own its own enter, exit, and loop animations directly — selecting a group shows the same animation controls as a single element. Group animations are **composed on top of** each child's own animation, so you can animate a whole group (for example, slide it in) without setting up each child individually, while children keep any animations of their own.

You can preview animations and export an animated scene as a GIF on the client side programmatically:

```ts
store.play();
store.stop();
await store.saveAsGIF();
```

## Video Export Options [#video-export-options]

Polotno supports two methods for exporting animated designs to MP4 video:

### Client-Side Video Export [#client-side-video-export]

For browser-based video generation without a server, use the `@polotno/video-export` package. All encoding happens directly in the user's browser:

```bash
npm install @polotno/video-export
```

```ts
import { storeToVideo } from '@polotno/video-export';

const videoBlob = await storeToVideo({
  store,
  fps: 30,
  pixelRatio: 2,
  onProgress: (progress) => {
    console.log(`Progress: ${Math.round(progress * 100)}%`);
  },
});

// Download the video
const url = URL.createObjectURL(videoBlob);
const link = document.createElement('a');
link.href = url;
link.download = 'video.mp4';
link.click();
```

Export speed depends on user hardware. High FPS or complex designs may take longer to process.

See the full [Video Export documentation](/docs/video-export) for complete API reference and live demo.

### Server-Side Video Export [#server-side-video-export]

For production-grade video rendering with consistent performance, use the [Cloud Render API](/docs/cloud-render-api). This option provides faster rendering and doesn't depend on client device capabilities.

## Audio Support [#audio-support]

Add background music or sound effects to your animated designs. Audio tracks sync with the video timeline and export together with animations.

See the [Audio documentation](/docs/audio) for complete details on adding and managing audio tracks.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-animations" />

## Related Pages [#related-pages]

* [Video Export](/docs/video-export) - Detailed client-side video export documentation
* [Audio](/docs/audio) - Add background music to animated designs
* [Cloud Render API](/docs/cloud-render-api) - Server-side video rendering
* [Import and Export](/docs/import-and-export) - Overview of all export formats


---

# Audio Support
URL: https://polotno.com/docs/audio



## Overview [#overview]

Polotno supports adding audio tracks to designs for video export. Audio files play during video rendering and can be trimmed, delayed, and volume-adjusted. Multiple audio tracks can be added to a single design.

Audio is stored at the **store level**, not per page. All pages/scenes share the same audio timeline when exporting to video. Combine audio with [animations](/docs/animations-and-videos) for complete multimedia designs.

## Adding Audio from the UI [#adding-audio-from-the-ui]

Users can upload audio files through the default **Upload** side panel:

1. Click the "Upload" section in the side panel
2. Select an audio file (MP3, WAV, OGG, etc.)
3. Click on added audio file or drag it to the workspace to add it to the design
4. The audio track appears in the **PagesTimeline** component at the bottom
5. Click the audio track in the timeline to trim, adjust volume, mute, duplicate, or remove it

## Programmatic API [#programmatic-api]

Add audio tracks programmatically using the Store API:

```ts
import { createStore } from 'polotno/model/store';

const store = createStore({ key: 'YOUR_KEY' });

// Add audio with default settings
store.addAudio({
  src: 'https://example.com/audio.mp3',
});

// Add audio with custom properties
store.addAudio({
  src: 'https://example.com/background-music.mp3',
  volume: 0.5,        // 50% volume (0 to 1)
  delay: 2000,        // Start after 2 seconds of video
  startTime: 0.25,    // Start from 25% into the audio file (0 to 1)
  endTime: 0.75,      // End at 75% into the audio file (0 to 1)
});
```

### Accessing and Removing Audio [#accessing-and-removing-audio]

```ts
// List all audio tracks
store.audios.forEach((audio) => {
  console.log(audio.id, audio.src, audio.volume);
});

// Remove audio by ID
const audioId = store.audios[0].id;
store.removeAudio(audioId);
```

See the full [Store API documentation](/docs/store#working-with-audio) for complete reference.

## Audio Properties [#audio-properties]

| Property    | Type   | Range | Description                                          |
| ----------- | ------ | ----- | ---------------------------------------------------- |
| `src`       | string | -     | URL or data URI of the audio file                    |
| `volume`    | number | 0-1   | Volume level (0 = mute, 1 = full)                    |
| `delay`     | number | 0+    | Milliseconds before audio starts in video timeline   |
| `startTime` | number | 0-1   | Relative start point in source file (0.5 = middle)   |
| `endTime`   | number | 0-1   | Relative end point in source file                    |
| `duration`  | number | -     | Duration of source audio in milliseconds (read-only) |

### Use Cases for Audio Properties [#use-cases-for-audio-properties]

**Background music with fade-in timing:**

```ts
store.addAudio({
  src: '/music.mp3',
  delay: 1000,      // Start 1 second into video
  volume: 0.3,      // Lower volume to not overpower content
});
```

**Use only the middle section of a long audio file:**

```ts
store.addAudio({
  src: '/podcast.mp3',
  startTime: 0.4,   // Skip first 40% of the file
  endTime: 0.6,     // End at 60% mark
});
```

**Sync audio to specific page timing:**

```ts
const pageDuration = store.pages[0].duration; // in ms
store.addAudio({
  src: '/narration.mp3',
  delay: pageDuration, // Start when page 2 begins
});
```

## Timeline Controls [#timeline-controls]

When you click an audio track in the **PagesTimeline**, the following controls are available:

* **Volume slider** -- adjust the playback volume of the track (0-100%)
* **Mute/unmute** -- quickly toggle audio on or off without changing the volume setting
* **Duplicate** -- create a copy of the audio track with the same settings
* **Trim** -- drag the edges of the track to set start and end points
* **Remove** -- delete the audio track from the design

These controls work the same way for programmatically added tracks and user-uploaded tracks.

## Export with Audio [#export-with-audio]

Audio tracks are included when exporting to video formats. The audio mixes down to the final video output.

For client-side video generation in the browser, use the [Video Export](/docs/video-export) package. For server-side rendering with consistent performance, use the [Cloud Render API](/docs/cloud-render-api). Both methods process all audio tracks and mix them into the final video.

## Audio Schema [#audio-schema]

Audio tracks are serialized in the design JSON. See the [Audio schema reference](/docs/schema/audio) for the complete data structure.

```json
{
  "audios": [
    {
      "id": "audio_1",
      "src": "https://example.com/audio.mp3",
      "duration": 180000,
      "startTime": 0,
      "endTime": 1,
      "volume": 1,
      "delay": 0
    }
  ]
}
```

## Live Demo [#live-demo]

Try adding audio to a design with this interactive example:

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-audio" />

## Notes [#notes]

<Callout type="info" title="Browser Audio Limits">
  Most browsers require **user interaction** (click, tap) before playing audio. Programmatic `store.play()` calls may be silent until the user interacts with the page.
</Callout>

<Callout type="warning" title="File Size Considerations">
  Audio files uploaded via the Upload panel are embedded as **base64 data URIs** by default. For production, implement a custom upload panel that stores files on your server and references them by URL. See [Upload Panel documentation](/docs/upload-panel).
</Callout>


---

# Canvas Rulers
URL: https://polotno.com/docs/canvas-rulers



Rulers in Polotno SDK's canvas editor ensure consistent alignment and precision, enhancing design cohesion. By defining guidelines and constraints, they streamline the design process, enabling users to create polished compositions efficiently.

### How to enable rulers? [#how-to-enable-rulers]

To control rulers from code, use the [Store API](/docs/store).

```ts
// hide/show rulers
store.toggleRulers();

// check if rulers are currently visible
console.log(store.rulersVisible);
```

## Ruler styling [#ruler-styling]

Customize the ruler appearance through [Workspace](/docs/workspace) props:

```tsx
<Workspace
  store={store}
  rulerBackgroundColor="#1e1e2e"  // ruler track background
  rulerTextColor="#cdd6f4"        // measurement labels
  rulerBorderColor="#585b70"      // border between ruler and canvas
  rulerBorderSize={1}             // border thickness in px
  rulerTickColor="#7f849c"        // tick marks along the ruler
  rulerTickSize={8}               // tick mark length in px
/>
```

All six props are optional and fall back to the built-in theme when omitted.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-rulers" />


---

# Custom Elements
URL: https://polotno.com/docs/custom-elements



**Important:** this is an experimental feature, please proceed with caution. We're kindly asking you to report any bugs and follow the [changelog](https://community.polotno.com/c/changelog) for the most recent updates.

Custom elements allow you to create your own shapes and add them to the canvas.

By design Polotno supports several main types of elements: `text`, `image`, `svg`, `line`, `figure`, `video`, `table`, `group`. In some cases you may want to create your own custom elements.

Before you start, please note that:

1. Custom elements are not supported in [Cloud Render API](/docs/cloud-render-api).
2. By default [polotno-node](/docs/server-side-image-generation-with-node-js) (for backend rendering) does not support custom elements. But with some [extra configuration](https://github.com/polotno-project/polotno-node#your-own-client) you can make it work.
3. You will need to know some Polotno internals to support animations for custom elements. Please write us if you need help.
4. In the future there will be more options for design export (e.g. to SVG, print‑ready PDF, etc). You will need to write some adapters to make it work with custom elements.
5. If possible, try to use built‑in elements. For example you can draw some complex shapes using `svg` element (you can generate `src` at runtime).

## How to create custom shapes with Polotno? [#how-to-create-custom-shapes-with-polotno]

As a demonstration, we will create a custom star element. Creating new elements consists of three main steps.

### 1. Create model for your element [#1-create-model-for-your-element]

First define any additional attributes for the new element. All the basic attributes such as `id`, `x`, `y`, `rotation`, filters attributes, etc. are defined by default. You only need to define extra fields and their defaults:

```ts
import { unstable_registerShapeModel } from 'polotno/config';

unstable_registerShapeModel(
  // define properties
  {
    type: 'star',
    radius: 100,
    fill: 'black',
    numPoints: 6,
  },
  // optional extend function
  (starModel) => {
    // starModel is a model from mobx-state-tree
    // we can define some additional methods here
    // and return it back
    return starModel.actions((self) => {
      return {
        setNumPoints(numPoints) {
          self.numPoints = numPoints;
        },
      };
    });
  }
);
```

Now Polotno store knows that we can define a `star` model.

### 2. Create React component for new element [#2-create-react-component-for-new-element]

Define how to display the model. Create a React component with react‑konva shapes.

```tsx
// polotno is made with mobx library
// we will need its tools to make reactive components
import { observer } from 'mobx-react-lite';
// import Konva components
import { Star } from 'react-konva';

import { unstable_registerShapeComponent } from 'polotno/config';

// now we need to define how element looks on canvas
export const StarElement = observer(({ element, store }) => {
  const ref = React.useRef<any>(null);

  const handleChange = (e: any) => {
    const node = e.currentTarget;
    const scaleX = node.scaleX();
    // Konva.Transformer changes scale by default; reset it
    node.scaleX(1);
    node.scaleY(1);
    // save changes back to the model
    element.set({
      x: node.x(),
      y: node.y(),
      rotation: e.target.rotation(),
      radius: element.radius * scaleX,
    });
  };

  // Important: element.x and element.y must define top-left corner of the shape
  // so positions are consistent across all elements
  return (
    <Star
      ref={ref}
      // use name="element" so Polotno can find the node
      name="element"
      id={element.id}
      x={element.x}
      y={element.y}
      fill={element.fill}
      offsetX={-element.radius}
      offsetY={-element.radius}
      rotation={element.rotation}
      opacity={element.opacity}
      draggable={!element.locked}
      outerRadius={element.radius}
      innerRadius={element.radius * 0.5}
      onDragMove={handleChange}
      onTransform={handleChange}
    />
  );
});

// register new component to draw our star
unstable_registerShapeComponent('star', StarElement);
```

### 3. Create custom top toolbar (optional) [#3-create-custom-top-toolbar-optional]

A custom toolbar can be defined to change star properties.

```tsx
import React from 'react';
import { observer } from 'mobx-react-lite';
import { NumericInput, Navbar } from 'polotno/primitives';

import ColorPicker from 'polotno/toolbar/color-picker';
import { unstable_registerToolbarComponent } from 'polotno/config';

const StarToolbar = observer(({ store }) => {
  const element = store.selectedElements[0];

  return (
    <Navbar.Group align="left">
      <ColorPicker
        value={element.fill}
        onChange={(fill) =>
          element.set({
            fill,
          })
        }
        store={store}
      />
      <NumericInput
        onValueChange={(radius) => {
          element.set({ radius });
        }}
        value={element.radius}
        min={1}
        max={200}
      />
    </Navbar.Group>
  );
});

unstable_registerToolbarComponent('star', StarToolbar);
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-custom-element" />


---

# Design Validation
URL: https://polotno.com/docs/design-validation



You can use the [Store API](/docs/store) to inspect each element's properties on the page, enabling thorough design checks and validation to custom standards. Define your own validation logic and display it however best fits your use case.

### Why Use Design Validation? [#why-use-design-validation]

Here are several common use cases where design validation can enhance the design workflow and final output:

1. **Compliance with Brand Guidelines**
   Ensure elements meet brand standards (e.g., font, color, size) by validating attributes against predefined values. For example, check if all text elements use a specific font or approved color palette.

2. **Image Quality Control**
   Validate image resolutions to confirm they meet print or screen quality standards, avoiding low‑quality images in high‑resolution exports.

3. **Layout Checks for Export**
   Review layout constraints to ensure elements are within the visible canvas and aligned correctly, preventing cut‑off or misplaced content in the final export.

4. **Content Accessibility**
   Check text elements for minimum font size, contrast, and positioning to ensure readability and accessibility compliance.

### Getting Started with the Store API [#getting-started-with-the-store-api]

The Store API gives you direct access to every element's properties on the canvas, making it easy to build custom validation checks for your specific needs:

```ts
const errors: { message: string; elementId: string }[] = [];

// Use "find" to iterate through all elements
store.find((item) => {
  // Perform validation checks on element properties
  if (item.type === 'text') {
    if (item.text.length > 300) {
      errors.push({
        message: 'Too long text',
        elementId: item.id,
      });
    }
  }
});

// then surface errors in your UI (e.g., toolbar, toast, side panel)
```

With Polotno’s Store API, you gain powerful control over your design quality, ensuring that each element aligns with your project standards before exporting or publishing.

## Demo [#demo]

In the demo there is a simple validation for position, font size, and image quality. The toolbar shows validation status. Click an issue to select the related element on the canvas.

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-design-validation" />


---

# Drawing Tool
URL: https://polotno.com/docs/drawing



The drawing tool allows users to create freehand drawings directly on the canvas. Drawings are automatically converted into SVG elements that can be edited, styled, and manipulated like any other element.

## How it works [#how-it-works]

**Default mode**: Polotno operates in `selection` mode, where users can click and select elements on the canvas.

**Drawing mode**: When activated, the canvas becomes a drawing area:

* All objects become non-clickable
* The entire canvas acts as a drawing surface
* Each stroke creates a new SVG element
* Users can change colors and properties after creation

## Activating drawing mode [#activating-drawing-mode]

Use the [Store API](/docs/store) to control the drawing tool programmatically.

```ts
// enable drawing mode
store.setTool('draw');

// return to selection mode
store.setTool('selection');
```

## Configuring drawing options [#configuring-drawing-options]

Before or during drawing mode, configure stroke properties:

```ts
store.setToolOptions({
  strokeWidth: 50,  // brush size in pixels
  stroke: 'red',    // stroke color (any CSS color)
  opacity: 0.4      // opacity from 0 to 1
});
```

## Full example [#full-example]

```ts
import { createStore } from 'polotno/model/store';

const store = createStore({ key: 'YOUR_API_KEY' });

// configure drawing options
store.setToolOptions({
  strokeWidth: 10,
  stroke: '#0066ff',
  opacity: 1
});

// enable drawing
store.setTool('draw');

// later, return to selection mode
store.setTool('selection');
```

## Editing drawn elements [#editing-drawn-elements]

After drawing, each stroke becomes an SVG element that users can:

* Select and move
* Resize and rotate
* Change fill color via properties panel
* Delete or duplicate
* Apply filters and effects

## Checking current tool [#checking-current-tool]

```ts
// check which tool is currently active
console.log(store.tool); // 'draw' or 'selection'

// check current tool options
console.log(store.toolOptions);
```

## Use cases [#use-cases]

* **Annotations**: Mark up designs with freehand notes
* **Signatures**: Capture digital signatures
* **Sketching**: Quick concept sketches over designs
* **Highlighting**: Draw attention to specific areas
* **Creative effects**: Add hand-drawn elements to designs


---

# Element Locking
URL: https://polotno.com/docs/element-locking



Element locking provides granular control over which aspects of an element users can modify. Polotno offers **6 independent locking properties** for precise interaction control.

**Quick start:** Use [User Roles](/docs/user-roles) with `store.setRole('admin')` for built-in locking UI. If you need custom controls, this page shows how to build your own.

## Locking properties [#locking-properties]

| Property          | Controls                             |
| ----------------- | ------------------------------------ |
| `selectable`      | Can element be selected and clicked? |
| `draggable`       | Can element be moved or rotated?     |
| `resizable`       | Can element be resized?              |
| `removable`       | Can element be deleted?              |
| `contentEditable` | Can element's content be changed?    |
| `styleEditable`   | Can element's style be changed?      |

All properties default to `true`.

## Basic usage [#basic-usage]

Lock an element programmatically:

```ts
element.set({
  draggable: false,      // Cannot move
  resizable: false,      // Cannot resize
  removable: false,      // Cannot delete
  contentEditable: false, // Cannot edit content
  styleEditable: false,  // Cannot change style
});

console.log(element.locked); // true
```

## Common patterns [#common-patterns]

**Template placeholder** — Users edit text, designer controls style:

```ts
element.set({
  contentEditable: true,  // Can edit text
  styleEditable: false,   // Cannot change appearance
  draggable: false,
  resizable: false,
});
```

**Non-interactive overlay** — Watermark, guide, or decoration:

```ts
element.set({
  selectable: false,  // Clicks pass through
  draggable: false,
  removable: false,
  alwaysOnTop: true,
});
```

**Fixed background** — Cannot move or delete, but can replace:

```ts
element.set({
  draggable: false,
  removable: false,
  contentEditable: true,  // Can change image
});
```

## Custom locking UI demo [#custom-locking-ui-demo]

This example demonstrates how to build custom lock controls without using admin mode. Select elements and use the 🔒 Locks tab to control their properties:

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-element-locking" />

## Related [#related]

* [User Roles](/docs/user-roles) — Admin mode for accessing locked elements
* [Overlays and Watermarks](/docs/overlays-and-watermarks) — Using `selectable`, `alwaysOnTop`, and `showInExport`
* [Element API](/docs/element) — Complete element property reference


---

# Fonts
URL: https://polotno.com/docs/fonts



Polotno supports three distinct font systems, each serving different purposes:

| Type             | Stored in JSON | User can remove | Use case                |
| ---------------- | -------------- | --------------- | ----------------------- |
| **Google Fonts** | No             | No              | Default font library    |
| **Design Fonts** | Yes            | Yes             | Per-design custom fonts |
| **Global Fonts** | No             | No              | App-wide custom fonts   |

## Google Fonts [#google-fonts]

By default, Polotno provides access to a large library of [Google Fonts](https://fonts.google.com/). These fonts appear in the font dropdown in the Text side panel.

### Customize the Google Fonts list [#customize-the-google-fonts-list]

```ts
import { setGoogleFonts } from 'polotno/config';

// limit to specific fonts only
setGoogleFonts(['Roboto', 'Open Sans', 'Lato']);

// disable Google Fonts entirely
setGoogleFonts([]);

// restore the full default list
setGoogleFonts('default');
```

### Customize font variants [#customize-font-variants]

By default, Polotno loads regular, italic, bold, and bold italic styles. You can customize which variants to load:

```ts
import { setGoogleFontsVariants } from 'polotno/config';

// default variants
setGoogleFontsVariants('400,400italic,700,700italic');

// load only regular and thin
setGoogleFontsVariants('400,100');
```

### Get Google Fonts API endpoints [#get-google-fonts-api-endpoints]

```ts
import { getGoogleFontsListAPI, getGoogleFontImage } from 'polotno/config';

// get URL to fetch the fonts list
const listUrl = getGoogleFontsListAPI();

// get preview image URL for a specific font
const previewUrl = getGoogleFontImage('Roboto');
```

```tsx
// example usage in JSX
<img src={getGoogleFontImage('Roboto')} alt="Roboto font preview" />
```

## Design Fonts [#design-fonts]

Design fonts are custom fonts attached to a specific design (JSON file). When you export with `store.toJSON()`, these fonts are included in the `fonts` array of the output.

**Key characteristics:**

* Stored in `store.fonts` and exported with `store.toJSON()`
* Visible in the fonts dropdown in the Text side panel
* Users can remove them via the default UI (removes the reference from JSON)
* Ideal for per-design or per-user custom fonts

### Add a design font [#add-a-design-font]

```ts
// simple usage with URL
store.addFont({
  fontFamily: 'MyCustomFont',
  url: 'https://example.com/fonts/MyFont.ttf',
});

// full control over font styles
store.addFont({
  fontFamily: 'MyCustomFont',
  styles: [
    {
      src: 'url("https://example.com/fonts/MyFont-Regular.ttf")',
      fontStyle: 'normal',
      fontWeight: 'normal',
    },
    {
      src: 'url("https://example.com/fonts/MyFont-Bold.ttf")',
      fontStyle: 'normal',
      fontWeight: 'bold',
    },
    {
      src: 'url("https://example.com/fonts/MyFont-Italic.ttf")',
      fontStyle: 'italic',
      fontWeight: 'normal',
    },
  ],
});

// register a font already loaded via CSS
store.addFont({
  fontFamily: 'MyCustomFont',
});
```

### Remove a design font [#remove-a-design-font]

```ts
store.removeFont('MyCustomFont');
```

### Load a font for rendering [#load-a-font-for-rendering]

Text elements on the canvas load fonts automatically. Use this method when you need to render fonts elsewhere in your UI (e.g., font picker preview):

```ts
await store.loadFont('MyCustomFont');
```

## Global Fonts [#global-fonts]

Global fonts are custom fonts registered at the application level. They are **not** stored in the design JSON, which keeps exports smaller. You control when and how to register these fonts.

**Key characteristics:**

* NOT included in JSON export (smaller file size)
* Developer controls when to add/remove them
* Can serve all users or specific users (your logic decides)
* Users cannot remove them via the default UI
* Must be manually added to JSON for [Cloud Render](/docs/cloud-render-api)

### Add a global font [#add-a-global-font]

```ts
import { addGlobalFont } from 'polotno/config';

// simple usage with URL
addGlobalFont({
  fontFamily: 'BrandFont',
  url: 'https://example.com/fonts/BrandFont.ttf',
});

// full control over font styles
addGlobalFont({
  fontFamily: 'BrandFont',
  styles: [
    {
      src: 'url("https://example.com/fonts/BrandFont-Regular.ttf")',
      fontStyle: 'normal',
      fontWeight: 'normal',
    },
    {
      src: 'url("https://example.com/fonts/BrandFont-Bold.ttf")',
      fontStyle: 'normal',
      fontWeight: 'bold',
    },
  ],
});

// register a font already loaded via CSS on the page
addGlobalFont({
  fontFamily: 'BrandFont',
});
```

### Remove a global font [#remove-a-global-font]

```ts
import { removeGlobalFont } from 'polotno/config';

removeGlobalFont('BrandFont');
```

### Replace all global fonts [#replace-all-global-fonts]

```ts
import { replaceGlobalFonts } from 'polotno/config';

replaceGlobalFonts([
  { fontFamily: 'Font1', url: 'https://example.com/font1.ttf' },
  { fontFamily: 'Font2', url: 'https://example.com/font2.ttf' },
]);
```

### Frameworkless integration [#frameworkless-integration]

For iframe or frameworkless integrations, use the global config object:

```ts
window.polotnoConfig.addGlobalFont({
  fontFamily: 'BrandFont',
  url: 'https://example.com/fonts/BrandFont.ttf',
});
```

## Global Fonts and Cloud Render [#global-fonts-and-cloud-render]

<Callout type="warning">
  Global fonts are **not** included in the JSON export. If you use [Cloud Render API](/docs/cloud-render-api), designs using global fonts will fail to render correctly unless you manually include the fonts.
</Callout>

Before sending JSON to Cloud Render, add the required global fonts to the `fonts` array:

```ts
const json = store.toJSON();

// manually add global fonts used in this design
json.fonts = [
  ...json.fonts,
  {
    fontFamily: 'BrandFont',
    url: 'https://example.com/fonts/BrandFont.ttf',
  },
];

// send to Cloud Render
await fetch('https://api.polotno.com/api/render', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    design: json,
    outputFormat: 'png',
    // ... other options
  }),
});
```

## When to Use Each Font Type [#when-to-use-each-font-type]

| Scenario                                 | Recommended type                 |
| ---------------------------------------- | -------------------------------- |
| Default fonts for all users              | Google Fonts or Global Fonts     |
| Brand fonts for your app                 | Global Fonts                     |
| User-uploaded custom fonts               | Design Fonts                     |
| Fonts that must persist in exported JSON | Design Fonts                     |
| Fonts for specific users (e.g., premium) | Global Fonts (add conditionally) |
| Keeping JSON files small                 | Global Fonts                     |

## Font Upload Configuration [#font-upload-configuration]

By default, users can upload fonts from the Text side panel. These are converted to Base64 and stored as design fonts.

To upload fonts to your server instead:

```ts
import { setFontUploadFunc } from 'polotno/config';

async function uploadFont(localFile: File): Promise<string> {
  const formData = new FormData();
  formData.append('file', localFile);
  
  const res = await fetch('https://your-server.com/upload-font', {
    method: 'POST',
    body: formData,
  });
  
  const { url } = await res.json();
  return url; // return the URL where the font is hosted
}

setFontUploadFunc(uploadFont);
```

## Related [#related]

* [Fonts & Text Consistency](/docs/fonts-consistency) — troubleshoot rendering differences across browsers and platforms
* [Store API](/docs/store#working-with-fonts) — full API reference for `store.addFont`, `store.removeFont`, `store.loadFont`
* [Cloud Render API](/docs/cloud-render-api) — server-side rendering with custom fonts


---

# Image Downscaling
URL: https://polotno.com/docs/image-downscaling



By default, Polotno uses an enhanced downscaling algorithm when images are scaled down on the canvas. This prevents common rendering artifacts that occur with the browser's default image scaling.

## The Problem [#the-problem]

When you scale down high-resolution images using the HTML5 canvas element, browsers use simple bilinear interpolation by default. This can produce visual artifacts like:

* Pixelation and jagged edges
* Moiré patterns on detailed images
* Loss of sharpness and clarity

This is especially noticeable when scaling images down significantly (e.g., displaying a 2000×2000px image at 200×200px).

## The Solution [#the-solution]

Polotno applies a multi-step downscaling algorithm that progressively reduces image size, producing smoother and higher-quality results. This technique is widely recommended for canvas-based image manipulation.

## Configuration [#configuration]

The downscaling feature is **enabled by default**. You can disable it if needed:

```ts
import { setDownScalingEnabled } from 'polotno/config';

// disable enhanced downscaling (use browser default)
setDownScalingEnabled(false);

// re-enable enhanced downscaling (default)
setDownScalingEnabled(true);
```

## When to Disable [#when-to-disable]

Consider disabling downscaling if:

* Performance is critical and you need faster rendering
* You're working with small images that don't benefit from the algorithm
* You prefer the browser's native rendering behavior

## Performance Impact [#performance-impact]

Enhanced downscaling uses additional CPU time during image rendering. For most use cases, the quality improvement outweighs the performance cost. On slower devices with many large images, disabling this feature may improve responsiveness.


---

# Overlays and watermarks
URL: https://polotno.com/docs/overlays-and-watermarks



In graphic design, controlling the behavior of elements is crucial for creating professional and efficient designs. Special properties like `selectable: false`, `alwaysOnTop: true`, and `showInExport: false` provide flexibility to manage overlays, watermarks, and guides seamlessly within your projects.

Common use cases:

* **Watermarks**: Protect designs while keeping them non-interactive.
* **Overlays**: Display information or graphics that stay visible without interfering with design interaction.
* **User Tips**: Provide guidance within the design that doesn't export with the final product.
* **Cutting Edges**: Keep guide marks visible only during the design process.

Here is how you can create such elements:

```ts
store.activePage.addElement({
  type: 'image',
  src: 'path-to-your-watermark-or-overlay.png',
  // make it non-selectable
  selectable: false,
  // keep it always on top
  alwaysOnTop: true,
  // hide it in export
  showInExport: false,
});
```

## Example [#example]

In the demo we add a dashed red shape on top of the design and make it non-selectable, always on top, and not visible in export. A regular user can't change it, but it is visible on the screen.

To control these properties via UI, use [User Roles](/docs/user-roles) admin mode or build [custom locking controls](/docs/element-locking).

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-overlay" />


---

# Page Bleed
URL: https://polotno.com/docs/page-bleed



In printing, bleed is printing that goes beyond the edge of where the sheet will be trimmed.

Polotno has native support for bleed. Every page has its own `bleed` property. By default bleeds are not visible on the workspace and export. To show bleed on the canvas:

```ts
store.activePage.set({ bleed: 20 }); // set bleed in pixels

// show bleed area on the <Workspace />
store.toggleBleed(true);
```

The canvas will have special space around the page where elements can extend beyond the trim line.

Users can also change bleed from the built-in **Size** side panel.

## Per-side bleed [#per-side-bleed]

Use `bleedTop`, `bleedRight`, `bleedBottom`, and `bleedLeft` to override the uniform `bleed` value for individual sides:

```ts
store.activePage.set({
  bleed: 20, // base value for all sides
  bleedBottom: 40, // override just the bottom side
});
```

Per-side values are honored on the canvas and in all exports.

## Exporting with Bleed [#exporting-with-bleed]

By default, exports do not include the bleed area. Use `includeBleed` option to export with bleed:

```ts
// export PDF with bleed
await store.saveAsPDF({ includeBleed: true });

// export image with bleed
await store.saveAsImage({ includeBleed: true });

// as data URL
await store.toDataURL({ includeBleed: true });
```

The built-in **Download** button includes bleed in its PDF exports automatically.

For detailed information on PDF exports with bleed and crop marks, see [PDF Export](/docs/pdf-export).

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-page-bleed" />


---

# Remove Image Background
URL: https://polotno.com/docs/remove-image-background



Polotno provides built-in UI for removing image backgrounds using AI. This feature integrates with the [Remove Background API](/docs/remove-background-api) and appears in the image toolbar once enabled.

## Enable the toolbar button [#enable-the-toolbar-button]

```ts
import { setRemoveBackgroundEnabled } from 'polotno/config';

setRemoveBackgroundEnabled(true);
```

<Callout type="warn">
  The "Remove Background" button is **disabled by default** for all plans. Call `setRemoveBackgroundEnabled(true)` during app initialization to expose it.
</Callout>

* **Pricing**: Additional usage charges apply. See [pricing details](https://polotno.com/sdk/pricing) for rates

## Disable the Feature [#disable-the-feature]

If you want to hide the "Remove Background" button later:

```tsx
import { Toolbar } from 'polotno/toolbar/toolbar';

<Toolbar
  store={store}
  components={{
    ImageRemoveBackground: () => null,
  }}
/>
```

## Requirements [#requirements]

1. **API Key**: Valid Polotno API key with Business plan (or Team plan with feature enabled)
2. **Network Access**: Internet connectivity required to call the cloud API

## How It Works [#how-it-works]

Once enabled, users will see a "Remove Background" button in the image element toolbar. Clicking it:

1. Sends the image to Polotno's cloud API
2. Processes the image with AI background removal
3. Returns a transparent PNG
4. Updates the canvas element with the result

For programmatic background removal without the UI, use the [Remove Background API](/docs/remove-background-api) directly:

```ts
const req = await fetch(
  'https://api.polotno.com/api/remove-image-background?KEY=YOUR_API_KEY',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url: 'path-to-image' }),
  }
);
const res = await req.json();
// returns base64 data URL with transparent background
const newImageURL = res.url;
```

<Callout type="warn">
  **Image Storage**: By default, the API returns a base64-encoded image which is saved directly into your design JSON. This increases JSON size significantly. **It is strongly recommended** to upload the processed image to your own cloud storage and store only the URL in the design JSON.
</Callout>

Example with cloud upload:

```ts
// after getting the base64 result
const res = await req.json();
const base64Image = res.url;

// upload to your cloud storage
const uploadedURL = await uploadToYourCloud(base64Image);

// update the element with the cloud URL instead of base64
element.set({ src: uploadedURL });
```

## Limitations [#limitations]

* Internet connection required
* Processing time varies based on image size and complexity
* Works best with clear subject separation from background

## Error Handling [#error-handling]

If the API call fails (network error, quota exceeded, invalid key), users will see an error message in the UI. Ensure your API key is valid and your subscription is active.

## Security & Privacy [#security--privacy]

**Data Storage**: Polotno does not store processed images. All images are processed transiently and deleted immediately after processing.

**Third-Party Service**: Background removal uses [Replicate](https://replicate.com/) as the processing provider. By using this feature, processed images are sent to Replicate's infrastructure.

**Terms**: Review [Replicate's Terms of Service](https://replicate.com/terms) if you have compliance requirements about where image data is processed.


---

# Rich Text
URL: https://polotno.com/docs/rich-text



A single text element can hold **multiple fonts, sizes, colors, weights, styles, and decorations** per span — you can style parts of the text independently. Internally, rich text is stored as an HTML string in `element.text`.

```ts
store.activePage.addElement({
  type: 'text',
  text: 'Hello <strong>from rich</strong> <u>text</u> <span style="color: red;">support</span>!',
  y: 300,
  x: store.width / 2 - 200,
  fontSize: 80,
  width: 400,
});
```

<Callout type="note">
  **Rich text now works out of the box — there is nothing to enable.** As of Polotno 3.x / 4.x, the new text rendering engine is the default and renderer switching is gone. The old `setRichTextEnabled` toggle is now a **no-op**, kept only so existing code doesn't break. The legacy `unstable_useHtmlTextRender` flag and the `htmlTextRenderEnabled` parameter are deprecated too.
</Callout>

## Reading and writing text format [#reading-and-writing-text-format]

The recommended way to read and change formatting is the headless format API. It works on any text element without touching the editor's internals.

```ts
import { getTextFormat, applyTextFormat } from 'polotno/utils/text-format';

// read the effective format of an element
const format = getTextFormat(element);
// each key reports whether the value is uniform or mixed across spans:
// { value, mixed, values }
console.log(format.fontWeight.value); // numeric weight, e.g. 400 or 700; undefined if mixed
console.log(format.fill.mixed); // true when the element uses more than one color

// apply a GLOBAL change — sets the element-level prop and strips inline
// per-span overrides so the new value shows uniformly
applyTextFormat(element, { fontWeight: 700 }); // any numeric weight; 'bold'/'normal' work as aliases

// works on an array too (batched into a single undo step)
applyTextFormat(store.selectedElements, { fill: '#ff0000', fontSize: 48 });
```

The formattable keys are `fontSize`, `fontFamily`, `fill`, `fontWeight`, `fontStyle`, and `textDecoration`.

### Build a format toolbar (React) [#build-a-format-toolbar-react]

The `useTextFormat` hook subscribes to the active selection and re-renders on change. When a text element is in edit mode, `applyTextFormat` applies to the current in-editor selection; otherwise it applies to the whole selected element(s).

```tsx
import { observer } from 'mobx-react-lite';
import { useTextFormat } from 'polotno/utils/text-format-state';

const FormatBar = observer(({ store }) => {
  const { format, enabled, applyTextFormat } = useTextFormat(store);
  if (!enabled) return null;

  const isBold = format.fontWeight.value >= 600;
  return (
    <button
      // prevent the in-editor selection from being lost on click
      onMouseDown={(e) => e.preventDefault()}
      onClick={() => applyTextFormat({ fontWeight: isBold ? 400 : 700 })}
    >
      Bold {format.fontWeight.mixed ? '(mixed)' : ''}
    </button>
  );
});
```

### Vue / vanilla JS [#vue--vanilla-js]

For non-React UIs, use `getTextFormatState` to read once, or `observeTextFormatState` to subscribe (it fires immediately and on every relevant change, and returns an unsubscribe function).

```ts
import {
  getTextFormatState,
  observeTextFormatState,
} from 'polotno/utils/text-format-state';

// read once
const { format, enabled, applyTextFormat } = getTextFormatState(store);

// or subscribe
const unsubscribe = observeTextFormatState(store, (state) => {
  // update your UI from state.format / state.enabled
  // call state.applyTextFormat({ ... }) to change formatting
});
```

## Font size and inline overrides [#font-size-and-inline-overrides]

A text element has a base `fontSize`, and individual spans may carry their own inline sizes. How you change the size depends on what you want to happen to those inline sizes:

**Make the whole element one uniform size** — `applyTextFormat` sets the base size and strips inline per-span sizes:

```ts
import { applyTextFormat } from 'polotno/utils/text-format';

applyTextFormat(element, { fontSize: 24 });
```

**Scale every span proportionally** — keep the relative differences between spans and scale them all by a factor with the `scaleRichTextFontSizesInHtml` helper, updating `fontSize` and `text` together:

```ts
import { scaleRichTextFontSizesInHtml } from 'polotno/utils/rich-text-html';

const factor = 24 / element.fontSize;
element.set({
  fontSize: 24,
  text: scaleRichTextFontSizesInHtml(element.text, factor),
});
```

**Change only the base size, leaving inline sizes untouched** — a plain `set`:

```ts
element.set({ fontSize: 24 });
```

## Advanced: direct Quill access [#advanced-direct-quill-access]

In most cases the [format API above](#reading-and-writing-text-format) is all you need. For lower-level control, Polotno uses [Quill](https://quilljs.com/) under the hood. When a text element is in "edit mode" (the user double‑clicks it) you can reach the live editor:

<Callout type="note">
  The Quill `bold` format used in the examples below is deprecated. It still works as an alias, but prefer the numeric `font-weight` format, e.g. `quill.format('font-weight', '700')`.
</Callout>

```ts
import { quillRef } from 'polotno/canvas/html-element';

// will log observable object with format of current selection
console.log(quillRef.currentFormat);

// will log current Quill editor instance. if text is not in edit mode, it will return null
console.log(quillRef.editor.instance);

<Button
  // (!) IMPORTANT to prevent default behaviour
  // so the quill editor doesn't lose the focus!
  onMouseDown={(e) => {
    e.preventDefault();
  }}
  onClick={() => {
    // if you want to change format to bold of current selection:
    const quill = quillRef.editor.instance;
    const selection = quill.getSelection();
    // toggle bold for selection
    quill.formatText(
      selection.index,
      selection.length,
      'bold',
      !quillRef.currentFormat.bold,
      'user'
    );
  }}
/>
```

In many cases, you may want to change format while a text element is not in edit mode. In that case you can create a Quill instance temporarily in memory → apply changes → save resulted HTML into the element.

```ts
import { createQuill, setQuillContent } from 'polotno/canvas/html-element';

// function to create quill instance in memory
const createTempQuill = ({ html }: { html: string }) => {
  const el = document.createElement('div');
  document.body.appendChild(el);
  el.style.display = 'none';
  el.style.whiteSpace = 'pre-wrap';
  const quill = createQuill(el);
  // use setQuillContent function to preserve some history edge cases
  setQuillContent(quill, html);
  return quill;
};

// remove quill when finished
const removeTempQuill = (quill: any) => {
  quill.root.parentElement.remove();
};

// example usage
const quill = createTempQuill({ html: element.text });
quill.setSelection(0, quill.getLength(), 'api');
// remove bold from text
quill.format('bold', false);
const innerHtml = quill.root.innerHTML;
// remove quill from memory
removeTempQuill(quill);
// save HTML back to element
element.set({ text: innerHtml });
```

Here is a full real‑world example of a "bold" format button:

```tsx
const ToggleButton = observer(
  ({
    active,
    globalActive,
    // name of the format
    format,
    element,
    disableGlobal,
    enableGlobal,
    icon,
  }: {
    active: boolean;
    globalActive: boolean;
    format: string;
    element: TextElementType;
    disableGlobal: () => void;
    enableGlobal: () => void;
    icon: any;
  }) => {
    return (
      <Button
        minimal
        icon={icon}
        active={active}
        onMouseDown={(e) => {
          e.preventDefault();
        }}
        onClick={(e) => {
          let quill = (window as any).__polotnoQuill;

          if (quill) {
            const selection = quill.getSelection();
            quill.formatText(
              selection.index,
              selection.length,
              format,
              !quillRef.currentFormat[format],
              'user'
            );
            if (globalActive) {
              disableGlobal();
            }
            return;
          }

          // if whole text selected, let's remove bold from inner
          quill = createTempQuill({ html: element.text });
          quill.setSelection(0, quill.getLength(), 'api');
          quill.format(format, false);
          const innerHtml = quill.root.innerHTML;
          removeTempQuill(quill);
          element.set({ text: innerHtml });

          if (globalActive) {
            disableGlobal();
          } else {
            enableGlobal();
          }
        }}
      />
    );
  }
);

export const TextBold = observer(({ element, store }: any) => {
  return (
    <ToggleButton
      format="bold"
      active={
        quillRef.currentFormat.bold ||
        element.fontWeight === 'bold' ||
        element.fontWeight === '700'
      }
      globalActive={
        element.fontWeight === 'bold' || element.fontWeight === '700'
      }
      element={element}
      disableGlobal={() => element.set({ fontWeight: 'normal' })}
      enableGlobal={() => element.set({ fontWeight: 'bold' })}
      icon={<Bold />}
    />
  );
});
```

## Define quill editor formats [#define-quill-editor-formats]

You can hook into the quill editor to change the list of available formats or define your own:

```ts
import { unstable_setQuillFormats } from 'polotno/config';

unstable_setQuillFormats([
  // default list of formats
  'bold',
  'color',
  'font',
  'italic',
  'size',
  'strike',
  'underline',
  'indent',
  'list',
  'direction',
  // add additional format
  'font-weight'
]);

// implement a new format with quill API
import Quill from 'quill';
const Inline = Quill.import('blots/inline');

class FontWeightBlot extends Inline {
  static create(value: any) {
    const node = super.create();
    node.style.fontWeight = value;
    return node;
  }

  static formats(node: HTMLElement) {
    return node.style.fontWeight;
  }
}

FontWeightBlot.blotName = 'font-weight';
FontWeightBlot.tagName = 'span';

Quill.register(FontWeightBlot);
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-rich-text" />

## Common Questions [#common-questions]

### Do I need to enable rich text? [#do-i-need-to-enable-rich-text]

No. Rich text is the default in Polotno 3.x / 4.x. The old `setRichTextEnabled` toggle is now a no-op kept only for backwards compatibility.

### Can I use rich text with server-side rendering? [#can-i-use-rich-text-with-server-side-rendering]

Yes. When using [Cloud Render API](/docs/cloud-render-api) or [polotno-node](/docs/server-side-image-generation-with-node-js), pass `richTextEnabled: true` in export options. (The legacy parameter `htmlTextRenderEnabled` is also supported but deprecated.)

### What HTML tags are supported? [#what-html-tags-are-supported]

Standard formatting tags: `<strong>`, `<em>`, `<u>`, `<span>`, and inline styles. See [Quill documentation](https://quilljs.com/) for complete details.


---

# Text Overflow
URL: https://polotno.com/docs/text-overflow



By default, text objects in Polotno expand their height whenever:

* You type additional text
* You change the text programmatically (via API)
* You set a larger font size

This behavior can be modified using the `setTextOverflow` method. It can be applied globally (once for all objects) or dynamically toggled when specific elements are selected.

```ts
import { setTextOverflow } from 'polotno/config';

// default, change height of the text object when it overflow defined width/height
setTextOverflow('resize');

// add ... at the end of the text when it overflow defined width/height
setTextOverflow('ellipsis');

// reduce font size to fit text in the defined width/height
// note, it will NOT increase font size back when there is more space
setTextOverflow('change-font-size');
```

You can use these settings in combination with
[setTextVerticalResizeEnabled](/docs/vertical-text-resize).

## Text Line Splitting [#text-line-splitting]

Control whether long text can split into multiple lines when it exceeds the width. Default is `false`.

```ts
import { unstable_setTextSplitAllowed } from 'polotno/config';

// allow text to split into multiple lines when width is exceeded
unstable_setTextSplitAllowed(true);

// disable text splitting (default)
unstable_setTextSplitAllowed(false);
```

When disabled (default), text remains on a single line and overflows according to the `setTextOverflow` setting. When enabled, text wraps to new lines automatically.

## Client-Side Default: resize overflow [#client-side-default-resize-overflow]

* Behavior: If the text exceeds its defined width or height, Polotno automatically increases the bounding box height to accommodate the content.
* Use Case: Interactive editing on the client, where resizing is more intuitive and immediate for users.

## Server-Side Default: change-font-size overflow [#server-side-default-change-font-size-overflow]

* Behavior: If the text exceeds its defined width or height during server-side rendering (e.g., using polotno-node or
  [Cloud Render API](/docs/cloud-render-api)), Polotno reduces the fontSize to ensure the text fits within the specified size.
* Use Case: Non-interactive scenarios where preserving a strict layout (width and height constraints) is important, and automatically shrinking text is preferable to resizing the layout.

## Motivation [#motivation]

Polotno automatically expands text on the client side because it feels more natural when you’re actively editing and want to see changes right away. This way, if you type more or increase the font size, the text box grows automatically to fit what you see on your screen.

On the server side, Polotno usually handles tasks like generating images or PDF documents where layouts need to stay consistent. Instead of enlarging the text box, it reduces the font size to fit the specified space. This approach avoids unexpected layout shifts and ensures your final output looks as intended without further adjustments.

In both scenarios, you can change the default behavior to fit your specific use case.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-text-overflow" />


---

# User Roles
URL: https://polotno.com/docs/user-roles





User roles in **Polotno Editor** change **UI behavior** for different workflows. Polotno has three built-in roles: **admin**, **user**, and **viewer**.

Note: Roles only affect **UI interactions**. Programmatic API (`element.set()`, `store.find()`, etc.) always works regardless of role.

## Roles overview [#roles-overview]

| Role               | Can edit elements | Can select locked elements | Access to locking UI | Typical use case                                      |
| ------------------ | ----------------- | -------------------------- | -------------------- | ----------------------------------------------------- |
| **user** (default) | Yes               | No                         | No                   | End users editing within defined constraints          |
| **admin**          | Yes               | Yes                        | Yes                  | Template creators, designers setting up restrictions  |
| **viewer**         | No                | No                         | No                   | Read-only previews, published designs, approval views |

## Setting a role [#setting-a-role]

```ts
// Set admin role (typically for template creators)
store.setRole('admin');

// Set user role (default, for end users)
store.setRole('user');

// Set viewer role (read-only, no editing)
store.setRole('viewer');

// Check current role
console.log(store.role); // 'admin', 'user', or 'viewer'
```

## Admin mode capabilities [#admin-mode-capabilities]

When **admin** mode is enabled, the UI changes:

1. **Select locked elements** — Can click and select elements marked as `selectable: false`
2. **Access locking UI** — Extra controls appear in the toolbar to set element restrictions
3. **Configure export behavior** — Toggle `showInExport` to hide elements from final output
4. **Fine-grained locking** — Control which aspects of an element can be edited (see [Element Locking](/docs/element-locking))

<img alt="Admin panel showing locking controls" src="__img0" />

## Viewer mode capabilities [#viewer-mode-capabilities]

When **viewer** mode is enabled, the canvas becomes **read-only**:

1. **No selection** — Elements can't be selected by clicking
2. **No editing** — Drag, resize, rotate, and inline text editing are all disabled
3. **No toolbars or context menus** — Element-specific UI is hidden
4. **Programmatic API still works** — You can drive the store from your own code

```ts
// Switch to read-only view
store.setRole('viewer');

// Programmatic changes still apply
store.activePage.children[0].set({ x: 100 });
```

Use viewer mode for design previews, gallery/published views, approval flows, or any surface where users should see a design but not modify it.

## Template creator workflow [#template-creator-workflow]

1. **Enable admin mode** — `store.setRole('admin')` to access all elements via UI
2. **Lock background elements** — Mark logos, borders, and guides as `selectable: false`
3. **Restrict editing** — Use `contentEditable: false` on text elements to prevent content changes
4. **Hide guides from export** — Set `showInExport: false` on helper elements
5. **Switch to user role** — Test the template with `store.setRole('user')` to verify restrictions

## Use cases [#use-cases]

### Non-editable overlays [#non-editable-overlays]

Use admin mode to create watermarks or logos that regular users can't select:

```ts
// As admin, create non-selectable element
store.activePage.addElement({
  type: 'image',
  src: 'logo.png',
  selectable: false,  // Regular users can't click it
  removable: false,
  alwaysOnTop: true,
});

// As admin, you can still select it by clicking
// Regular users (role: 'user') cannot
```

### Editable content with locked styling [#editable-content-with-locked-styling]

Create template placeholders where users can change text but not styling:

```ts
// Create element with mixed locks
store.activePage.addElement({
  type: 'text',
  text: 'Edit this text',
  contentEditable: true,  // Can edit text content
  styleEditable: false,   // Cannot change font, color, etc.
  draggable: false,       // Cannot move
  resizable: false,       // Cannot resize
});

// Admin can access locking UI to adjust these settings
// Regular users see the restrictions enforced
```

### Export-only guides [#export-only-guides]

Create guide layers visible during editing but hidden in exports:

```ts
store.activePage.addElement({
  type: 'figure',
  subType: 'rect',
  stroke: 'red',
  strokeWidth: 2,
  fill: 'transparent',
  selectable: false,
  showInExport: false, // Hidden in export
});

// Admin can toggle this via UI
// Regular users can't interact with it
```

## Role vs. programmatic API [#role-vs-programmatic-api]

**Role affects UI only.** The programmatic API always works:

```ts
// Programmatic API works the same in any role
element.set({ draggable: false, removable: false });

// No need to change role for programmatic operations
const locked = store.find((el) => el.selectable === false);
locked.forEach((el) => el.set({ x: 100 })); // Works in any role
```

## Custom locking UI [#custom-locking-ui]

Admin mode provides built-in UI for controlling locks. If you need more flexibility or want to integrate locking controls into your own interface, you can build custom UI.

See [Element Locking](/docs/element-locking) for:

* Complete locking API reference
* Live demo of custom locking UI
* Examples of building your own lock controls

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-admin-role" />


---

# Vertical Text Resize
URL: https://polotno.com/docs/vertical-text-resize



By default, you can't change **height** of **text** elements. Texts are always updating their own height to fit content. To modify it, consider setting a bounding box for text elements and replacing text content dynamically on the backend later on.

When vertical resize is enabled you can also set vertical align from the text toolbar.

### How to enable vertical text resize? [#how-to-enable-vertical-text-resize]

```ts
import { setTextVerticalResizeEnabled } from 'polotno/config';

setTextVerticalResizeEnabled(true);
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-vertical-text-resize" />


---

# Context Menu
URL: https://polotno.com/docs/context-menu





**ContextMenu** is a UI component that is rendered on right-click inside the page/workspace.

<img alt="Context Menu" src="__img0" />

## How to customize ContextMenu? [#how-to-customize-contextmenu]

You can pass a custom `ContextMenu` component into `<Workspace />` to overwrite the default one.

Warning: you will have to fully control every aspect of the context menu.

```tsx
import Workspace from 'polotno/canvas/workspace';

const ContextMenu = ({ store }) => {
  return <div>MyContextMenu</div>;
};

const App = ({ store }) => {
  return (
    <div
      style={{
        display: 'flex',
        height: '100%',
        margin: 'auto',
        flex: 1,
        flexDirection: 'column',
        position: 'relative',
      }}
    >
      <Workspace
        store={store}
        components={{
          ContextMenu,
        }}
      />
    </div>
  );
};
```

## How to disable ContextMenu? [#how-to-disable-contextmenu]

Pass a `ContextMenu` component that renders `null` to disable it.

```tsx
import Workspace from 'polotno/canvas/workspace';

const ContextMenu = () => null;

const App = ({ store }) => {
  return (
    <div
      style={{
        display: 'flex',
        height: '100%',
        margin: 'auto',
        flex: 1,
        flexDirection: 'column',
        position: 'relative',
      }}
    >
      <Workspace store={store} components={{ ContextMenu }} />
    </div>
  );
};
```


---

# Toolbar
URL: https://polotno.com/docs/toolbar





**Toolbar** is a UI components to change elements on the canvas, reorder and align them, apply undo/redo.

<img alt="Toolbar" src="__img0" />

Basic usage:

```tsx
import Toolbar from 'polotno/toolbar/toolbar';
import Workspace from 'polotno/canvas/workspace';

const App = ({ store }) => {
  return (
    <div
      style={{
        display: 'flex',
        height: '100%',
        margin: 'auto',
        flex: 1,
        flexDirection: 'column',
        position: 'relative',
      }}
    >
      <Toolbar store={store} />
      <Workspace store={store} />
    </div>
  );
};
```

Also `Toolbar` component has additional properties to hide some elements and overwrite inputs for some properties.

```ts
type ToolbarProps = {
  store: StoreType,
  downloadButtonEnabled?: Boolean,
  // see how to use it in the example below
  components?: any,
};

// example
<Toolbar store={store} downloadButtonEnabled />;
```

## How to overwrite available inputs for an element type? [#how-to-overwrite-available-inputs-for-an-element-type]

Toolbar supports special `components` property to add/change/remove most of its UI components.

In some application you may want to change available properties for selected element type. E.g. you may want to display a different color picker for text element. Just pass a component in format `TypeName` e.g. `TextFill`. You can use all built-element types as `Text`, `Image`, `Svg`. But also you can use `Many` prefix when several elements are selected. Also you can define your own new components for any element type. E.g. `ImageAlertButton`.

There are several built-in components but also you can add your own.

```
text element:
  TextFontFamily
  TextFontSize
  TextFontVariant
  TextFilters
  TextTransform
  TextFill
  TextSpacing
  TextAnimations
  TextAiWrite

image elements
  ImageFlip
  ImageFilters
  ImageFitToBackground
  ImageCrop
  ImageClip
  ImageRemoveBackground
  ImageAnimations

svg element:
  SvgFlip
  SvgFilters
  SvgColors
  SvgAnimations

line element:
  LineSettings
  LineColor
  LineHeads
  LineAnimations

figure element:
  FigureFill
  FigureStroke
  FigureSettings
  FigureFilters
  FigureAnimations

video element:
  VideoTrim
  VideoAnimations

table element:
  TableBorderSettings
  CellBackground
  TableStructure
  TextFontFamily (when cells focused)
  TextFontSize (when cells focused)
  TextFill (when cells focused)
  TextFontVariant (when cells focused)
  CellVerticalAlign (when cells focused)
  TextSpacing (when cells focused)
  TableAnimations

many elements selected:
  ManyAnimations

page (no elements selected):
  PageDuration
  PageBackground

common:
  History
  Group
  Position
  Opacity
  CopyStyle
  Lock
  Duplicate
  Remove
```

```tsx
import Toolbar from 'polotno/toolbar/toolbar';
import Workspace from 'polotno/canvas/workspace';
import { observer } from 'mobx-react-lite';

const MyColorPicker = observer(({ store, element, elements }) => {
  // store - main polotno store object
  // elements - array of selected elements. The same as store.selectedElements
  // element - first selected element. The same as store.selectedElements[0]
  return (
    <div>
      <input
        type="color"
        value={element.fill}
        onChange={(e) => {
          element.set({
            fill: e.target.value,
          });
        }}
      />
    </div>
  );
});

// as example lets disable font size input for text element
// just return null from your component
const TextTextFontSize = () => null;

// also we can invent our own new component
const TextAlertButton = observer(({ store, element, elements }) => {
  return (
    <button
      onClick={() => {
        alert('Hello!');
      }}
    >
      Alert
    </button>
  );
});

// also we can disable default Undo/Redo buttons via History component
const History = () => null;

const App = ({ store }) => {
  return (
    <div
      style={{
        display: 'flex',
        height: '100%',
        margin: 'auto',
        flex: 1,
        flexDirection: 'column',
        position: 'relative',
      }}
    >
      <Toolbar
        store={store}
        components={{
          TextFill: MyColorPicker,
          TextTextFontSize,
          TextAlertButton,
          History,
        }}
      />
      <Workspace store={store} />
    </div>
  );
};
```

## How to remove a specific button? [#how-to-remove-a-specific-button]

Create a React component that renders nothing (returns null) and overwrite the component in the toolbar.

```tsx
const None = () => null;

<Toolbar store={store} components={{ ImageRemoveBackground: None }} />
```

## How to overwrite all inputs at once? [#how-to-overwrite-all-inputs-at-once]

Following [Custom Element Example](/docs/custom-elements), you can make your own React component for any available element.

Recommendation: build your own UI with components from [`polotno/primitives`](/docs/customizations) so it matches the editor, and use `<Navbar.Group>` to group inputs. Also remember to wrap your component in `observer` from `mobx-react-lite` library to add automatic reactivity of your components.

```tsx
import React from 'react';
import { observer } from 'mobx-react-lite';
import { NumericInput, Navbar } from 'polotno/primitives';

import ColorPicker from 'polotno/toolbar/color-picker';
import { unstable_registerToolbarComponent } from 'polotno/config';

const TextToolbar = observer(({ store }) => {
  const element = store.selectedElements[0];

  return (
    <Navbar.Group align="left">
      <ColorPicker
        value={element.fill}
        onChange={(fill) =>
          element.set({
            fill,
          })
        }
        store={store}
      />
      <NumericInput
        onValueChange={(fontSize) => {
          element.set({ fontSize: fontSize });
        }}
        value={element.fontSize}
        min={1}
        max={40}
      />
    </Navbar.Group>
  );
});

unstable_registerToolbarComponent('text', TextToolbar);
```

## How to overwrite Download button [#how-to-overwrite-download-button]

On the right side of the toolbar, Polotno has 'Action Controls' section. You can use `components` prop to overwrite this section.

Recommendation: keep 'Action Controls' as small as possible. `<Toolbar />` component already has a lot of tools. So it is better give it as much available width as possible. You can put 'Action Controls" somewhere else in the UI of your application. For example, take a look into [https://studio.polotno.com/](https://studio.polotno.com/). Download button is placed on the top of the app instead of the `<Toolbar />`.

```tsx
import { Toolbar } from 'polotno/toolbar/toolbar';
import { Button } from 'polotno/primitives';
import { DownloadButton } from 'polotno/toolbar/download-button';

// it is important to define component onside of `MyToolbar` render function
const ActionControls = ({ store }) => {
  return (
    <div>
      <DownloadButton store={store} />
      <Button
        onClick={() => {
          alert('Saving');
        }}
      >
        Save
      </Button>
    </div>
  );
};

const MyToolbar = ({ store }) => {
  return (
    <Toolbar
      store={store}
      components={{
        ActionControls,
      }}
    />
  );
};
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-toolbar-actions" />


---

# Tooltip
URL: https://polotno.com/docs/tooltip





**Tooltip**, a UI component similar to the [Toolbar](./toolbar), is designed to change elements on the canvas, reorder and align them. It is rendered next to a selected element — a behavior you can modify.

<img src="__img0" />

## How to customize Tooltip? [#how-to-customize-tooltip]

Similar to the [Toolbar](./toolbar), Tooltip supports a special `components` property to add/change/remove most of its UI parts.

Pass a component using the name format `TypeName`, where `Type` refers to the element `type`. For example: `TextFill`. You can use built-in element types like `Text`, `Image`, `svg`. You can also use the `Many` prefix when several elements are selected. Additionally, you can define your own components for any element type, e.g. `ImageAlertButton`.

```tsx
import { observer } from 'mobx-react-lite';
import { Workspace } from 'polotno/canvas/workspace';
import { Tooltip } from 'polotno/canvas/tooltip';

const MyColorPicker = observer(({ store, element, elements }) => {
  // store - main polotno store object
  // elements - array of selected elements. Same as store.selectedElements
  // element - first selected element. Same as store.selectedElements[0]
  return (
    <div>
      <input
        type="color"
        value={element.fill}
        onChange={(e) => {
          element.set({
            fill: e.target.value,
          });
        }}
      />
    </div>
  );
});

const App = ({ store }) => {
  return (
    <div
      style={{
        display: 'flex',
        height: '100%',
        margin: 'auto',
        flex: 1,
        flexDirection: 'column',
        position: 'relative',
      }}
    >
      <Workspace
        store={store}
        components={{
          Tooltip,
          TextFill: MyColorPicker,
        }}
      />
    </div>
  );
};
```

Tip for images: prefix the component name with `Image`, for example `ImageActionButton: MyComponent`.

## How to disable Tooltip? [#how-to-disable-tooltip]

Pass a `Tooltip` component that renders `null`.

```tsx
import { Toolbar } from 'polotno/toolbar/toolbar';
import { Workspace } from 'polotno/canvas/workspace';

const Tooltip = () => null;

const App = ({ store }) => {
  return (
    <div
      style={{
        display: 'flex',
        height: '100%',
        margin: 'auto',
        flex: 1,
        flexDirection: 'column',
        position: 'relative',
      }}
    >
      <Toolbar store={store} />
      <Workspace store={store} components={{ Tooltip }} />
    </div>
  );
};
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-tooltip" />


---

# Workspace
URL: https://polotno.com/docs/workspace



**Workspace** is an essential part of **Polotno**. It is the main **React** component used to display drawings and interact with them. You can change canvas and its content programmatically using the [Store API](/docs/store).

```tsx
import { Workspace } from 'polotno/canvas/workspace';
import { createStore } from 'polotno/model/store';

const store = createStore({
  key: 'YOUR_API_KEY', // you can create it here: https://polotno.com/cabinet/
  // you can hide back-link on a paid license
  // but it will be good if you can keep it for Polotno project support
  showCredit: true,
});

const App = () => {
  return (
    <div style={{ height: '100vh' }}>
      <Workspace store={store} />
    </div>
  );
};
```

The `Workspace` will automatically take the full width and height of its parent, so you don't have to adjust its size manually. Set the size of the parent `div` with CSS.

## Layout orientation [#layout-orientation]

Control whether pages are stacked vertically (default) or horizontally in the workspace:

```tsx
// Default vertical layout (pages stack top to bottom)
<Workspace store={store} layout="vertical" />

// Horizontal layout (pages arranged left to right)
<Workspace store={store} layout="horizontal" />
```

**Use cases:**

* `vertical` (default): Standard multi-page documents, presentations, social media carousels
* `horizontal`: Timeline-based designs, panoramic layouts, storyboards

**Demo:**

Switch between vertical and horizontal orientation in this live editor. The store renders three pages so you can evaluate the timeline spacing.

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-workspace-layout" />

## Customize page controls [#customize-page-controls]

You can customize page controls of your `<Workspace />` component. Remove buttons, add your own, etc. You are in complete control over what is shown around the page.

```tsx
<Workspace
  store={store}
  components={{
    PageControls: ({ width, height, xPadding, yPadding }) => (
      <div
        style={{
          position: 'absolute',
          top: yPadding + 'px',
          left: xPadding + 'px',
        }}
      >
        My controls here...
      </div>
    ),
  }}
/>
```

## Hide page controls [#hide-page-controls]

Optionally, you can hide UI to add/remove/duplicate pages.

```tsx
<Workspace store={store} components={{ PageControls: () => null }} />
```

## Workspace styling [#workspace-styling]

Optionally, change some styles of the workspace.

```tsx
<Workspace
  store={store}
  backgroundColor="grey"
  pageBorderColor="black" // border around page
  activePageBorderColor="red" // border around active page (used when there are several pages)
  bleedColor="rgba(255, 0, 0, 0.2)" // color of the bleed area, toggled via store.toggleBleed()
  // optionally change default padding around page content
  // you can set it to 0 if you want full width and height of the canvas
  paddingX={50}
  paddingY={50}
  pageGap={50} // distance in pixels between pages, useful for multi-page layouts
  altCloneEnabled={true} // enable alt+drag to clone objects, default is true

  selectionRectFill="rgba(0, 161, 255, 0.3)"
  selectionRectStroke="rgb(0, 161, 255)"
  selectionRectStrokeWidth={1}

  snapGuideStroke="rgb(0, 161, 255)"
  snapGuideStrokeWidth={1}
  snapGuideDash={[4, 6]}
  
  transformLabelFill="rgb(0, 161, 255)"
  transformLabelTextFill="white"

  distanceGuideStroke="rgb(0, 161, 255)"
  distanceLabelFill="rgb(0, 161, 255)"
  distanceLabelTextFill="white"

  // ruler styling (see Canvas Rulers docs for details)
  rulerBackgroundColor="#f0f0f0"
  rulerTextColor="#333"
  rulerBorderColor="#ccc"
  rulerBorderSize={1}
  rulerTickColor="#999"
  rulerTickSize={8}

  // selection transformer (resize handles around selected element)
  // accepts Konva.TransformerConfig; omitted fields keep default values
  transformerStyle={{ anchorStroke: 'red', borderStroke: 'red' }}

  // hover/highlight rectangle around elements
  highlighterStyle={{ stroke: 'rgb(0, 161, 255)', strokeWidth: 2 }}

  // image crop transformers (inner = over cropped image, outer = source bounds)
  innerImageCropTransformerStyle={{ borderStroke: 'red' }}
  outerImageCropTransformerStyle={{ borderStroke: 'red' }}

  // dim overlay drawn around the canvas while an image is in crop mode
  cropOverlayFill="rgba(0,0,0,0.3)"

  // background + spinner color for image/video/gif elements while loading
  mediaLoadingStyle={{ fill: 'rgba(124, 173, 212, 0.8)', textFill: 'white' }}

  // background + text color for image/video/gif elements that failed to load
  mediaErrorStyle={{ fill: 'rgba(223, 102, 102, 0.8)', textFill: 'white' }}

  // stroke color for the (hidden) text overflow indicator path
  textOverflowIndicatorStyle={{ stroke: 'red' }}

  // Controls auto-scroll when the active page changes.                                                                
  // When a new page becomes active, the workspace scrolls to it only if                                               
  // the current scroll position is farther than this threshold from the page.                                         
  // Value is a fraction of the page size (0.5 = 50% of page height/width).                                            
  // Default 0.5. Increase to reduce scrolling. Use Infinity to disable completely.                                    
  scrollToPageThreshold={0.5}

// by default polotno will use checkerboard background for transparency, you can change it to any color you want
  transparencyBackgroundColor="grey" 

  // optionally set safe area for tooltip to avoid overlapping with other elements that you may place on top of the workspace
  tooltipSafeArea={{
    top: 100,
    right: 100,
    bottom: 100,
    left: 100,
  }}
/>
```

> **Deprecated.** `setTransformerStyle`, `setHighlighterStyle`,
> `setInnerImageCropTransformerStyle`, and
> `setOuterImageCropTransformerStyle` from `polotno/config` do the same
> thing globally and still work for backwards compatibility, but prefer
> the per-`<Workspace>` props above. The setters will be removed in the
> next major.

## Read-only view [#read-only-view]

To render the workspace as a non-editable preview, switch the store to the `viewer` role. Selection, drag, resize, and inline editing are disabled while the canvas continues to render normally.

```tsx
store.setRole('viewer');
```

See [User Roles](/docs/user-roles) for the full behavior of each role.

## Group selection [#group-selection]

`groupSelectionMode` controls how clicks on grouped elements behave inside the canvas.

```tsx
// default — clicking a child inside a group selects that child
<Workspace store={store} groupSelectionMode="drill" />

// legacy — clicking anywhere inside a group selects the whole group
<Workspace store={store} groupSelectionMode="group" />
```

* `"drill"` (default): the first click on a group selects the group as a whole. A second click on the already-selected group drills in and selects the clicked child.
* `"group"`: the group is always selected as a single unit, no matter how many times you click. Use this for the previous (pre-drill) behavior where children can only be reached via the layers panel or `store.selectElements`.

The mode does not affect programmatic selection — `store.selectElements([childId])` works the same way regardless of which mode is active.

## Select through stacked elements [#select-through-stacked-elements]

Hold `Cmd` (macOS) or `Ctrl` (Windows/Linux) while clicking to cycle the selection through elements stacked at the click point. This is useful for picking an element that sits behind another.

## Show only the current page in Workspace [#show-only-the-current-page-in-workspace]

Use the `renderOnlyActivePage` property to show only the active page.

```tsx
<Workspace renderOnlyActivePage />
```

## No pages UI [#no-pages-ui]

If your `store` has no pages, `<Workspace />` will show a simple UI with a button to create a new page. You can overwrite this UI with your own.

```tsx
<Workspace
  store={store}
  components={{
    NoPages: ({ store }) => <div>The project has no pages...</div>,
  }}
/>
```

## Overwrite keyboard handler [#overwrite-keyboard-handler]

If you don't like default keyboard shortcuts, you can overwrite them with your own.

```tsx
import { handleHotkey } from 'polotno/canvas/hotkeys';

<Workspace
  store={store}
  onKeyDown={(e, store) => {
    if (e.key === 'Escape') {
      store.selectElements([]);
      return;
    }
    // optionally call the default handler
    handleHotkey(e, store);
  }}
/>;
```

<Callout type="warn">
  Do not call `e.preventDefault()` for `Ctrl/Cmd + C/X/V` in a custom
  `onKeyDown` handler. Copy, cut, and paste are handled through the browser's
  native clipboard events (which also power pasting external images and text
  onto the canvas), and preventing the default keydown action suppresses those
  events entirely — copy/paste will silently stop working.
</Callout>


---

# Asset Loading Configuration
URL: https://polotno.com/docs/asset-loading



Polotno provides methods to control how assets (images, fonts) are loaded, including timeout settings and error handlers.

## Asset Load Timeout [#asset-load-timeout]

Configure how long Polotno waits before timing out asset loads (images, SVGs). Default: 30 seconds.

```ts
import { setAssetLoadTimeout } from 'polotno/config';

// set timeout to 10 seconds
setAssetLoadTimeout(10000);
```

## Font Load Timeout [#font-load-timeout]

Configure timeout specifically for font loading. Default: 6 seconds.

```ts
import { setFontLoadTimeout } from 'polotno/config';

// set font timeout to 15 seconds
setFontLoadTimeout(15000);
```

## Error Handling [#error-handling]

Register a global error handler for asset loading failures. The handler receives an `Error` with a `code` property and structured `details`, so you can react differently per failure type:

```ts
import { onLoadError } from 'polotno/config';

onLoadError((error) => {
  if (error.code === 'IMAGE_FAILED') {
    console.error(
      `Image failed to load (element ${error.details?.elementId}):`,
      error.message
    );
  } else if (error.code === 'FONT_FAILED') {
    console.error(`Font "${error.details?.family}" failed to load`);
  } else {
    console.error('Failed to load asset:', error.message);
  }
});
```

See [Error Handling](/docs/error-handling) for the full list of codes and the `details` they carry. The same codes are reported when rendering through [polotno-node](/docs/server-side-image-generation-with-node-js).

<Callout type="info">
  Before polotno 4.3.0 the handler received a plain string. It now receives the `Error` above — `error.message` contains the old string.
</Callout>

## Custom Image Loader (Advanced) [#custom-image-loader-advanced]

<Callout type="warn">
  **Advanced Feature**: This is an experimental API for complex scenarios. Not supported in [Cloud Render API](/docs/cloud-render-api) or [polotno-node](/docs/server-side-image-generation-with-node-js).
</Callout>

Override the default image loading mechanism with a custom React hook. The hook must follow the [react-konva useImage hook](https://konvajs.org/docs/react/Images.html) pattern, returning `[image, status]`.

```tsx
import React from 'react';
import { unstable_setImageLoaderHook } from 'polotno/config';

function useCustomImageLoader(url, crossOrigin) {
  const [image, setImage] = React.useState(null);
  const [status, setStatus] = React.useState('loading');

  React.useEffect(() => {
    if (!url) return;
    
    setStatus('loading');
    const img = document.createElement('img');
    
    const onLoad = () => {
      setStatus('loaded');
      setImage(img);
    };
    
    const onError = () => {
      setStatus('failed');
      setImage(null);
    };
    
    img.addEventListener('load', onLoad);
    img.addEventListener('error', onError);
    
    if (crossOrigin) {
      img.crossOrigin = crossOrigin;
    }
    img.src = url;
    
    return () => {
      img.removeEventListener('load', onLoad);
      img.removeEventListener('error', onError);
    };
  }, [url, crossOrigin]);
  
  return [image, status];
}

// register the custom hook
unstable_setImageLoaderHook(useCustomImageLoader);
```

### Use Cases [#use-cases]

* **Authentication**: Modify URLs or add auth tokens before loading
* **S3 Link Revalidation**: Refresh expired pre-signed URLs
* **Custom CDN Logic**: Route requests through specific endpoints
* **Retry Logic**: Implement automatic retries on failure


---

# Error Handling
URL: https://polotno.com/docs/error-handling



Every Polotno package reports failures the same way: a plain `Error` with a `code` property and a structured, JSON-serializable `details` object. Consuming code branches on `error.code` — the same pattern Node.js itself uses (`err.code === 'ENOENT'`):

```ts
import { jsonToPDFBytes, type PolotnoError } from '@polotno/pdf-export';

try {
  await jsonToPDFBytes(design);
} catch (e) {
  const error = e as PolotnoError;
  if (error.code === 'IMAGE_FAILED') {
    // which element failed:
    console.log(error.details.elementId);
    if (error.details.reason === 'unsupported-format') {
      // e.g. 'application/pdf' — an embedded PDF passed as an image
      console.log(error.details.mimeType);
    }
  } else {
    throw e;
  }
}
```

There are no error classes and no `instanceof` checks. A property check works across bundle copies, worker threads, and serialization boundaries — codes even survive the headless-browser boundary inside [`polotno-node`](/docs/server-side-image-generation-with-node-js), where thrown errors are rehydrated with `code` and `details` intact.

## Codes vs. messages [#codes-vs-messages]

Branch on `error.code` and `details.reason`, not on `error.message`. Codes are meant to stay stable across releases; messages are human-readable text and may be reworded at any time — log them, display them, but don't match on them.

## Error codes [#error-codes]

`details.reason` carries the fine grain within a code; the other `details` fields tell you what exactly failed.

| Code             | When                                                                                 | Key `details`                                                                                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DESIGN_INVALID` | Design JSON failed validation (schema check, `store.loadJSON`, unknown element type) | `errors` — array of `{ path, message }`                                                                                                                                      |
| `EXPORT_FAILED`  | An export could not run or an element failed to render                               | `reason`: `page-not-found`, `workspace-not-mounted`, `unmounted-during-export`, `invalid-options`, `element`, `busy`, `pdfx` — plus `pageId`, `option`, `label`, `elementId` |
| `IMAGE_FAILED`   | An image could not be loaded, decoded, or embedded                                   | `reason`: `unsupported-format`, `load`, `decode-failed`, `fetch-failed`, `invalid-data-url`, `timeout` — plus `mimeType`, `supported`, `src`, `elementId`                    |
| `FONT_FAILED`    | A font could not be resolved or loaded                                               | `reason`: `not-found`, `timeout`, `fetch-failed`, `decode-failed` — plus `family`, `src`                                                                                     |
| `VIDEO_FAILED`   | A video could not be loaded, decoded, or encoded                                     | `reason`: `load`, `no-video-track`, `unsupported-codec`, `cannot-decode`, `no-encoder`, `zero-duration`, `invalid-dimensions`, `timeout` — plus `src`                        |
| `FETCH_FAILED`   | A network request for an asset failed (after retries, where applicable)              | `url`, `status`, `attempts`                                                                                                                                                  |
| `IMPORT_FAILED`  | An imported file (PSD / SVG / PDF) could not be parsed                               | `format`: `psd`, `svg`, `pdf`                                                                                                                                                |
| `UNKNOWN`        | An unclassified failure reported through `onLoadError`                               | —                                                                                                                                                                            |

The original low-level error, when there is one, is chained as `error.cause`.

## Where errors come from [#where-errors-come-from]

Each package throws only the codes relevant to it:

| Package                                                             | Codes you can catch                                                                                                                                            |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `polotno` (editor)                                                  | `DESIGN_INVALID`, `EXPORT_FAILED` from store methods; `IMAGE_FAILED`, `VIDEO_FAILED`, `FONT_FAILED`, `UNKNOWN` via [`onLoadError`](#onloaderror-in-the-editor) |
| `polotno-node`                                                      | Everything the editor reports, rehydrated across the browser boundary, plus `FETCH_FAILED` and `EXPORT_FAILED` (`reason: 'busy'`)                              |
| `@polotno/pdf-export`                                               | `DESIGN_INVALID`, `IMAGE_FAILED`, `EXPORT_FAILED`, `FONT_FAILED`, `FETCH_FAILED`                                                                               |
| `@polotno/pptx-export`                                              | `DESIGN_INVALID`, `IMAGE_FAILED`, `EXPORT_FAILED`, `FETCH_FAILED`                                                                                              |
| `@polotno/video-export`                                             | `VIDEO_FAILED`, `FETCH_FAILED`, `EXPORT_FAILED`                                                                                                                |
| `@polotno/psd-import`, `@polotno/svg-import`, `@polotno/pdf-import` | `IMPORT_FAILED`                                                                                                                                                |
| `@polotno/schema`                                                   | `DESIGN_INVALID`                                                                                                                                               |

## `onLoadError` in the editor [#onloaderror-in-the-editor]

Exports and imports **throw**. The editor canvas is different: a broken image or font inside the editor should not crash rendering, so those failures are **reported** instead — to the global `onLoadError` handler. The error object has exactly the same shape as thrown errors:

```ts
import { onLoadError } from 'polotno/config';

onLoadError((error) => {
  if (error.code === 'IMAGE_FAILED') {
    notifyUser(`An image could not be loaded (element ${error.details?.elementId})`);
  } else if (error.code === 'FONT_FAILED') {
    notifyUser(`Font "${error.details?.family}" could not be loaded`);
  }
});
```

See [Asset Loading Configuration](/docs/asset-loading) for timeouts and the rest of the loading configuration.

## TypeScript [#typescript]

Every package exports the `PolotnoError` interface and a `PolotnoErrorCode` union of the codes that package throws, so comparing `error.code` against a misspelled code is a compile-time error:

```ts
import type { PolotnoError, PolotnoErrorCode } from '@polotno/pdf-export';
// in the editor:
import type { PolotnoError } from 'polotno/utils/errors';
```


---

# Fonts & Text Consistency
URL: https://polotno.com/docs/fonts-consistency



<Callout type="info">
  This page covers **rendering consistency** issues. For general font configuration (adding fonts, Google Fonts, etc.), see the [Fonts guide](/docs/fonts).
</Callout>

<Callout type="note">
  Polotno renders text using the browser's native text rendering engine. Different browsers and operating systems may produce slightly different results. This guide covers best practices to minimize these differences.
</Callout>

## The Problem [#the-problem]

Ever seen text look different between browsers? Or your server-side export doesn't match what users see? Common causes:

* Font files with incorrect metadata (weight class, vertical metrics)
* Mismatched family names or weight declarations
* Browsers synthesizing missing bold/italic faces differently

***

## How to Declare Fonts [#how-to-declare-fonts]

How you declare fonts depends on whether your font file includes multiple variations:

### Single file with all variations [#single-file-with-all-variations]

If your font file includes **all variations** (normal, bold, italic, bold+italic)—such as variable fonts:

```json
{
  "fontFamily": "FiraSans",
  "url": "url('/fonts/FiraSans-VariableFont.ttf')"
}
```

### Separate files for each weight/style [#separate-files-for-each-weightstyle]

If you have **separate files** (most common), register them as one family:

```json
{
  "fontFamily": "FiraSans",
  "styles": [
    {
      "src": "url('/fonts/FiraSans-Regular.ttf')",
      "fontStyle": "normal",
      "fontWeight": 400
    },
    {
      "src": "url('/fonts/FiraSans-Bold.ttf')",
      "fontStyle": "normal",
      "fontWeight": 700
    },
    {
      "src": "url('/fonts/FiraSans-Italic.ttf')",
      "fontStyle": "italic",
      "fontWeight": 400
    }
  ]
}
```

**❌ Don't do this:**

```json
// Don't register bold as a separate family!
{
  "fontFamily": "FiraSans-Bold",  // Wrong
  "styles": [...]
}
```

***

## Font File Quality [#font-file-quality]

For consistent rendering, font files need proper metadata:

**Weight class matches declaration**

* Internal `usWeightClass` should match your `fontWeight` value
* Example: Bold file should have `usWeightClass=700` and `fontWeight: 700`

**Consistent vertical metrics**

* All faces in a family (Regular, Bold, Italic) must share the same ascender, descender, and line-gap
* Mismatched metrics cause baseline shifts and spacing differences

**Aligned naming tables**

* Use consistent family/subfamily names across all faces
* Example: "Fira Sans" and "FiraSans" might be treated as different families

**Web-ready format**

* Use TTF, WOFF, or WOFF2 formats
* Keep identical metrics across all format conversions

***

## When to Normalize [#when-to-normalize]

Normalize fonts if you see:

* Different line spacing on macOS vs Windows
* Bold weight looks different across browsers
* Server exports don't match preview
* Inconsistent third-party fonts

**Font normalization** fixes the metadata issues above. You'll need to build your own server-side process using tools like:

* **gftools + fonttools** (Python-based, good for automation)
* **FontForge** (GUI or scriptable)
* **Online converters** like [Transfonter](https://transfonter.org/) (for testing)

<Callout type="warn">
  Font normalization requires server-side implementation. All faces in a family must share identical vertical metrics.
</Callout>

***

## Validate Uploaded Fonts [#validate-uploaded-fonts]

If users can upload custom fonts, validate them to catch issues early:

**Check on upload:**

* Weight class matches user selection
* Vertical metrics are consistent across font faces
* No duplicate or conflicting family names

**Handle issues:**

* Warn if metadata doesn't match declarations
* Optionally auto-normalize and store processed versions
* Use font parsing libraries to extract metadata


---

# How to Resolve CORS Issues
URL: https://polotno.com/docs/how-to-resolve-cors-issues



In order to load images into the canvas element, Polotno sets the `crossOrigin` attribute to `anonymous` by default. In some configurations you may see an error like this:

*Access to image at '[http://example.com/image.jpg](http://example.com/image.jpg)' from origin '[http://your-domain.com](http://your-domain.com)' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.*

Here's the fix:

## 1. Make sure assets are served with CORS headers [#1-make-sure-assets-are-served-with-cors-headers]

First, ensure that the server hosting your images allows CORS requests. If you control the server, add the header `Access-Control-Allow-Origin: *` to the response.

If you use an S3 bucket, enable CORS in the bucket settings. See AWS docs: [https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html](https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html)

## 2. Make sure all images have `crossOrigin` attribute [#2-make-sure-all-images-have-crossorigin-attribute]

Before adding images into the canvas, you may want to display them somewhere else in your application UI (e.g., a side panel or pre‑editor step). Make sure that all images have the `crossOrigin` attribute set to `anonymous`. For example, if you use an `img` tag:

```html
<img src="http://example.com/image.jpg" crossOrigin="anonymous" />
```

Explanation: if you load the same image in the same browsing session without the `crossOrigin` attribute, and later load it with `crossOrigin`, the browser will enforce CORS because it was initially fetched without the expected setting. Always include `crossOrigin="anonymous"` consistently.


---

# Mobile Support
URL: https://polotno.com/docs/mobile-support





## Does Polotno support mobile and touch devices? [#does-polotno-support-mobile-and-touch-devices]

Yes. You can use it on mobile and touch devices to create beautiful designs. Polotno adapts to mobile and touch environments, ensuring a smooth, optimized design experience on any screen size.

<img alt="Mobile" src="__img0" />

Note: Polotno SDK is primarily designed to work in web environments (not native apps). However, you can still use it in your app where a WebView is available.

## How to toggle mobile mode on large screens? [#how-to-toggle-mobile-mode-on-large-screens]

In some cases you may want to force compact/mobile view on a large screen (e.g., when embedding the editor in a sidebar). Add the `polotno-mobile` class to any parent container of the Polotno editor, such as the `body` tag:

```html
<body class="polotno-mobile">
  <div id="root"></div>
</body>
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-mobile" />


---

# React Version Support
URL: https://polotno.com/docs/react-19-support



Polotno targets **React 19** by default. Just install the package:

```bash
npm i polotno
```

This is the **4.x** line and the recommended choice for new and existing projects.

## React 18 (legacy, available for now) [#react-18-legacy-available-for-now]

A separate **3.x** line still supports React 18, published under the `next-react18` tag:

```bash
npm i polotno@next-react18
```

Both lines track the same features today, but **React 18 support is being phased out**. If you're on React 18, plan to upgrade to React 19 so you can move to the default `4.x` line — we recommend not starting new projects on the React 18 line.

<Callout type="note">
  **Migrating from Polotno 2?** The default UI changed in 3.x / 4.x. See the [Polotno 4 Migration](/docs/polotno-4-migration) guide.
</Callout>

## Troubleshooting [#troubleshooting]

If you see a peer dependency error like this during install:

> npm error Could not resolve dependency:
>
> npm error peer react@"^18.x" from polotno

…your React version doesn't match the installed line. On React 19 use `npm i polotno`; if you're still on React 18, use `npm i polotno@next-react18`.


---

# Reactivity and Events
URL: https://polotno.com/docs/reactivity-and-events



Polotno's state is an [**mobx-state-tree store**](https://mobx-state-tree.js.org/), so every change is observable through [MobX](https://mobx.js.org/).

In React, you get automatic UI updates by wrapping your components in `observer()`:

```tsx
import { observer } from 'mobx-react-lite';

// the component will be automatically updated when number of children is changed
export const App = observer(({ store }) => (
  <div>
    <p>Elements on the current page: {store.activePage?.children.length}</p>
  </div>
));
```

You can also use any data from the store as dependency to react hooks:

```tsx
const App = observer(({ store }) => {
  React.useEffect(() => {
    console.log('width of the store is changed');
  }, [store.width]);
  return <></>;
})
```

### React hooks + MobX reactions [#react-hooks--mobx-reactions]

If you want logic that runs outside the render cycle, you can combine `useEffect` with `mobx.reaction` (or `autorun`):

```tsx
import { reaction } from 'mobx';
import { useEffect } from 'react';

export function useElementCounter(store) {
  useEffect(() => {
    // fires every time the number of elements on the active page changes
    const dispose = reaction(
      () => store.activePage?.children.length,
      (length) => {
        console.log('Element count changed:', length);
      }
    );
    return dispose;          // clean-up on unmount
  }, [store]);               // deps
}
```

Under the hood, MobX tracks exactly what you read inside the first function and re-runs the second function only when that value changes—no manual listeners, no polling.

## Events [#events]

`store.on('change', handler)` is the only event we fire. It triggers on any mutation: add, remove, move, resize, undo, redo, you name it.

```tsx
const unsubscribe = store.on('change', () => {
  console.log('Something in the store changed');
});
```

### Detecting specific actions [#detecting-specific-actions]

Because every action funnels through the same event, you filter manually.

**Example: Simple tracking of adding/removing elements**

```tsx
let prevCount = store.activePage?.children.length ?? 0;

const unsub = store.on('change', () => {
  const newCount = store.activePage?.children.length ?? 0;

  if (newCount > prevCount) {
    console.log('Element added');
  } else if (newCount < prevCount) {
    console.log('Element removed');
  }

  prevCount = newCount;
});
```

**Example: deeper tracking of adding/removing elements**

If you need more gradual control, you can save more references to previous data to have a deeper diff.

```tsx
let lastIds = {};

store.on('change', () => {
   const newIds = {};
   store.find(item => {
     newIds[item.id] = item;
   })
   for (const id in lastIds) {
      const deleted = !newIds[id];
      if (deleted) {
         console.log(id, 'deleted');
      }
   }
   for (const id in newIds) {
      const added = !lastIds[id];
      if (added) {
         console.log(id, 'added');
      }
   }
   lastIds = newIds;
});
```

**Example: Changes on one element**

```tsx
import { reaction } from 'mobx';

function watchElement(element) {
  return reaction(
    () => ({
      x: element.x,
      y: element.y,
      width: element.width,
      height: element.height,
      rotation: element.rotation,
    }),
    (coords) => {
      console.log('Element changed', coords);
    }
  );
}

// later
const dispose = watchElement(store.activePage.children[0]);
```

**Example: Page-level changes (title, background, etc.)**

```tsx
reaction(
  () => ({
    title: store.activePage?.name,
    bg: store.activePage?.background,
  }),
  (data) => console.log('Page updated', data)
);
```

### Performance [#performance]

`change` event can fire **dozens of times per second** during drag/resize. Avoid heavy work inside the handler - wrap it in throttle, or debounce.

```tsx
// define function to save design to backend
const saveDesign = async () => {
  // export the design
  const json = store.toJSON();
  // save it to the backend
  await fetch('https://example.com/designs', {
    method: 'POST',
    body: JSON.stringify(json),
  });
}

// write a function for throttle saving
// it will call save no more then 1 time per second
let timeout = null;
const requestSave = () => {
  // if save is already requested - do nothing
  if (timeout) {
    return;
  }
  // schedule saving to the backend
  timeout = setTimeout(() => {
    // reset timeout
    timeout = null;
    saveDesign();
  }, 1000);
};

// request saving operation on any changes
store.on('change', requestSave);
```


---

# Remove Background API
URL: https://polotno.com/docs/remove-background-api



## How to use the Remove Background feature programmatically? [#how-to-use-the-remove-background-feature-programmatically]

As part of the Business plan, you can use the API to remove backgrounds from images. To call the API from your app:

```ts
const req = await fetch(
  'https://api.polotno.com/api/remove-image-background?KEY=YOUR_API_KEY',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url: 'path-to-image-or-base64-dataurl' }),
  }
);
if (req.status !== 200) {
  throw new Error('Error while removing background');
}
const res = await req.json();
// returns base64 data URL
return res.url;
```


---

# Saving custom data into a design
URL: https://polotno.com/docs/saving-custom-data-into-a-design



## How to save additional metadata into a design? [#how-to-save-additional-metadata-into-a-design]

In some use cases, you may want to save your own data into the store/page/element. You may want to save:

* Name of the design
* Design id
* Custom page properties
* Element metadata

For such use cases, you can use the `custom` attribute. It is available for all nodes in the store: the store itself, any page, any element.

```ts
// set custom data
element.set({
  custom: {
    // optionally, keep previous custom data
    ...element.custom,
    // save new data
    price: 10,
  },
});

// read custom data
// notice that by default element.custom will be null
const price = element.custom?.price;

// also you can save metadata into a page
page.set({
  custom: {
    ...page.custom,
    reference: 'sample',
  },
});

// or into store
store.set({
  custom: {
    productId: 'some-id',
  },
});
```

`custom` must be an object `{}`. You can write any data into that object. Polotno never uses it for rendering, so it is under your control. By default, `custom` will be `null`, so when you read some data from `custom`, make sure it is defined.

The `custom` attribute is included in [JSON export](/docs/import-and-export) via `store.toJSON()`, making it perfect for saving metadata that travels with your design templates.

## Use Cases [#use-cases]

* **Template variables**: Store variable names for [dynamic template generation](/docs/dynamic-template-variables)
* **Design metadata**: Save author, version, or creation date
* **Element IDs**: Track external database references
* **QR code data**: Store encoded content for [QR code elements](/docs/qr-codes)


---

# Store Observer and Reactions
URL: https://polotno.com/docs/store-observer-and-reactions



Polotno has a rich [store API](/docs/store) that you can use to observe and control canvas content. The store object is created using the MobX library. You can use MobX utilities to build reactive components.

## Observable component [#observable-component]

To create a component that updates automatically when the canvas changes, use the `observer` API from `mobx-react-lite`:

```tsx
import { observer } from 'mobx-react-lite';
import { createStore } from 'polotno/model/store';

const store = createStore({
  key: 'YOUR_API_KEY', // you can create it here: https://polotno.com/cabinet/
});

// this react component is wrapped into observer
// it will be automatically updated when number of elements on active page changes
const App = observer(() => {
  return (
    <div>
      <p>Elements on the current page: {store.activePage?.children.length}</p>
    </div>
  );
});
```

## Store reaction [#store-reaction]

The `store` object has a `change` event triggered when canvas content is modified. Selecting/deselecting elements will NOT trigger the `change` event.

```ts
store.on('change', () => {
  console.log('something is changed');
});
```

In some cases, you may want to react to selection or other data changes in the store. Use MobX `reaction` or `autorun`:

```ts
import { reaction } from 'mobx';

const dispose = reaction(
  () => {
    const firstElement = store.selectedElements[0];
    const isTextSelected = firstElement?.type === 'text';
    return isTextSelected;
  },
  (isTextSelected) => {
    // here we can do something when text is selected
    console.log('text is selected', isTextSelected);
  }
);

// later when no longer needed
dispose();
```


---

# Units and Measures
URL: https://polotno.com/docs/units-and-measures



## What metrics are using in Polotno? [#what-metrics-are-using-in-polotno]

By default Polotno is using CSS **pixels** as units with **1pt = 1px** and **72dpi**. Everything you see in the **store** is in **pixels** – **width**, **height** or **fontSize**; Polotno will use these values in UI.

You can change units displayed in UI using **setUnits** method.

```ts
store.setUnit({
  unit: 'mm', // mm, cm, in, pt, px
  dpi: 300,
});
```

## How to display units in custom UI? [#how-to-display-units-in-custom-ui]

Also you can use special functions to convert units to pixels and back:

```ts
import { pxToUnitRounded, unitToPx, pxToUnit } from 'polotno/utils/unit';

// convert 100 pixels to mm with 300 DPI
var mm = pxToUnit({
  px: 100,
  unit: 'mm',
  dpi: 300,
});

// do the same, but with 2 digits rounding, so number doesn't look ugly long in UI
var mm = pxToUnitRounded({
  px: 100,
  unit: 'mm',
  precious: 2,
  dpi: 300,
});

// convert 30 mm to pixels with 300 DPI
var pixels = unitToPx({
  unit: 'mm',
  dpi: 300,
  unitVal: 30,
});
```

## Exports and DPI [#exports-and-dpi]

When you [export your design to PDF](/docs/pdf-export), Polotno will use 72 DPI to determine the size of the exported pages. If you increase just the dpi, it will not change quality of the exported PDF. It will just produce a PDF file with smaller page sizes. You have two options to increase quality of your exported designs:

1. Use high **pixelRatio** attribute when you do the export. `store.saveAsPDF({ pixelRatio: 2 })`
2. Change DPI and change ALL pixels values in the store.

### DPI Metadata in PNG and JPEG Exports [#dpi-metadata-in-png-and-jpeg-exports]

For PNG and JPEG exports, Polotno can embed DPI resolution metadata directly into the image file. This is useful for print workflows where downstream software needs to know the intended print resolution.

```ts
// Embed 300 DPI metadata
await store.saveAsImage({ dpi: 300 });

// Control when metadata is embedded
await store.toDataURL({ 
  dpi: 300, 
  dpiMetadata: 'auto' // 'auto' | 'always' | 'never'
});
```

**Behavior:**

* `dpiMetadata: 'auto'` (default) — Embeds DPI only when it differs from 72
* `dpiMetadata: 'always'` — Always embeds DPI metadata
* `dpiMetadata: 'never'` — Never embeds DPI metadata

The `dpi` parameter defaults to `store.dpi` if not specified. DPI metadata embedding only works with PNG and JPEG formats, not PDF or other formats.

## Common Questions [#common-questions]

### How do I create print-ready designs? [#how-do-i-create-print-ready-designs]

Use `store.setUnit({ unit: 'mm', dpi: 300 })` to work in print units. For export quality, increase `pixelRatio` in [PDF export](/docs/pdf-export).

### Why doesn't changing DPI improve export quality? [#why-doesnt-changing-dpi-improve-export-quality]

DPI only affects UI display and page dimensions, not render quality. Use `pixelRatio` in [export functions](/docs/import-and-export) to increase quality.

### Can I mix units in a design? [#can-i-mix-units-in-a-design]

The canvas editor internally uses pixels. Units are for display only. Use conversion functions to work with different units programmatically.


---

# Background side panel customization
URL: https://polotno.com/docs/background-side-panel-customization



You can change the default search query used in the background side panel:

```ts
import { setDefaultQuery } from 'polotno/side-panel/background-panel';

setDefaultQuery('city');
```

You can't change other aspects of the default background side panel. If you need more customizations, remove the default panel and implement your own version for full control.

You can change the default color preset using this:

```ts
import { setBackgroundColorsPreset } from 'polotno/side-panel/background-panel';

setBackgroundColorsPreset(['red', 'green']);
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-background-sidepanel" />


---

# Custom images panel
URL: https://polotno.com/docs/custom-images-panel



## How to load custom photos in the side panel? [#how-to-load-custom-photos-in-the-side-panel]

Using the customization API, you can add a new section to the Side Panel to display images from any remote API or your own backend.

You can write a custom panel that loads images from an API:

```tsx
import React from 'react';
import { observer } from 'mobx-react-lite';
import { SearchInput } from 'polotno/primitives';
import { SectionTab } from 'polotno/side-panel';
import { ImagesGrid } from 'polotno/side-panel/images-grid';
import { getImageSize } from 'polotno/utils/image';
import MdPhotoLibrary from '@meronex/icons/md/MdPhotoLibrary';

export const PhotosPanel = observer(({ store }) => {
  const [images, setImages] = React.useState<Array<{ url: string }>>([]);

  async function loadImages() {
    // implement your API requests here
    setImages([]);

    // emulate network request
    await new Promise((resolve) => setTimeout(resolve, 3000));

    // demo data; in a real app use an API response
    setImages([
      { url: './carlos-lindner-zvZ-HASOA74-unsplash.jpg' },
      { url: './guillaume-de-germain-TQWJ4rQnUHQ-unsplash.jpg' },
    ]);
  }

  React.useEffect(() => {
    loadImages();
  }, []);

  return (
    <div style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
      <SearchInput
        placeholder="Search..."
        onChange={() => {
          loadImages();
        }}
        style={{ marginBottom: 20 }}
      />
      <p>Demo images:</p>
      {/* you can create your own custom component here */}
      {/* but we will use built-in grid component */}
      <ImagesGrid
        images={images}
        getPreview={(image) => image.url}
        onSelect={async (image, pos, element, event) => {
          // image - an item from your array
          // pos - relative mouse position on drop. undefined if user just clicked
          // element - model from your store if image was dropped on an element
          // event - can contain additional data
          const { width, height } = await getImageSize(image.url);
          store.activePage?.addElement({
            type: 'image',
            src: image.url,
            width,
            height,
            x: pos?.x || 0,
            y: pos?.y || 0,
          });
        }}
        rowsNumber={2}
        isLoading={!images.length}
        loadMore={false}
      />
    </div>
  );
});

// define the new custom section
export const CustomPhotos = {
  name: 'photos',
  Tab: (props) => (
    <SectionTab name="Photos" {...props}>
      <MdPhotoLibrary />
    </SectionTab>
  ),
  Panel: PhotosPanel,
};
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-load-custom-images" />


---

# Customizing Resize Panel
URL: https://polotno.com/docs/customizing-resize-panel



## How to set your own default page sizes? [#how-to-set-your-own-default-page-sizes]

You can make your own panel from scratch and define new Sizes section. For example:

```tsx
import React, { useState, useEffect } from 'react';
import { observer } from 'mobx-react-lite';
import {
  Button,
  NumericInput,
  Select,
  SelectTrigger,
  SelectContent,
  SelectItem,
  SelectValue,
} from 'polotno/primitives';
import { pxToUnitRounded, unitToPx } from 'polotno/utils/unit';

const MIN_PX = 10;

const PRESETS = [
  { label: 'IG Post', w: 1080, h: 1080, unit: 'px' },
  { label: 'IG Story', w: 1080, h: 1920, unit: 'px' },
  { label: 'Full HD', w: 1920, h: 1080, unit: 'px' },
  { label: 'A4', w: 21, h: 29.7, unit: 'cm' },
  { label: 'Letter', w: 8.5, h: 11, unit: 'in' },
];

export const ResizePanel = observer(({ store }) => {
  const [w, setW] = useState(0);
  const [h, setH] = useState(0);

  useEffect(() => {
    setW(
      pxToUnitRounded({ px: store.width, unit: store.unit, dpi: store.dpi })
    );
    setH(
      pxToUnitRounded({ px: store.height, unit: store.unit, dpi: store.dpi })
    );
  }, [store.width, store.height, store.unit, store.dpi]);

  const applyResize = (unitW = w, unitH = h) => {
    const widthPx = unitToPx({
      unitVal: unitW,
      unit: store.unit,
      dpi: store.dpi,
    });
    const heightPx = unitToPx({
      unitVal: unitH,
      unit: store.unit,
      dpi: store.dpi,
    });
    if (widthPx >= MIN_PX && heightPx >= MIN_PX)
      store.setSize(widthPx, heightPx, true);
  };

  const Row = ({ children }) => (
    <div
      style={{
        display: 'flex',
        alignItems: 'center',
        gap: 8,
        marginBottom: 10,
      }}
    >
      {children}
    </div>
  );

  return (
    <div style={{ padding: 16, overflowY: 'auto', maxHeight: '100%' }}>
      <Row>
        <div style={{ width: 60 }}>Width</div>
        <NumericInput value={w} onValueChange={setW} min={1} />
      </Row>
      <Row>
        <div style={{ width: 60 }}>Height</div>
        <NumericInput value={h} onValueChange={setH} min={1} />
      </Row>
      <Row>
        <div style={{ width: 60 }}>Units</div>
        <Select
          value={store.unit}
          onValueChange={(unit) => store.setUnit({ unit, dpi: store.dpi })}
        >
          <SelectTrigger style={{ width: '100%' }}>
            <SelectValue />
          </SelectTrigger>
          <SelectContent>
            {['px', 'cm', 'in'].map((u) => (
              <SelectItem key={u} value={u}>
                {u}
              </SelectItem>
            ))}
          </SelectContent>
        </Select>
      </Row>
      <Button
        onClick={() => applyResize()}
        style={{ width: '100%', marginBottom: 16 }}
      >
        Resize
      </Button>

      {/* preset buttons, one per row */}
      {PRESETS.map(({ label, w: pw, h: ph, unit }) => (
        <Button
          key={label}
          style={{ width: '100%', height: 60, marginBottom: 8 }}
          onClick={() => {
            store.setUnit({ unit, dpi: store.dpi });
            applyResize(pw, ph);
          }}
        >
          {label}
          <span style={{ fontSize: '0.75em', marginLeft: 6, opacity: 0.7 }}>
            {pw}×{ph} {unit}
          </span>
        </Button>
      ))}
    </div>
  );
});
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-resize-panel" />


---

# Hidden panels
URL: https://polotno.com/docs/hidden-panels



## Built-in hidden panels [#built-in-hidden-panels]

Polotno includes several internal hidden panels that are not shown in the tab bar but open programmatically via `store.openSidePanel(name)`. These panels are triggered by toolbar buttons (e.g. clicking "Effects" in the image toolbar opens the `effects` panel).

| Panel name   | Description                              | Triggered by         |
| ------------ | ---------------------------------------- | -------------------- |
| `effects`    | Image/element filters and effects editor | Toolbar "Effects"    |
| `animation`  | Animation settings for selected element  | Toolbar "Animate"    |
| `image-clip` | Image clipping / mask editor             | Toolbar "Apply mask" |

```ts
// Open the built-in effects panel for the selected element
store.openSidePanel('effects');

// Open the animation panel
store.openSidePanel('animation');

// Open the image clip/mask panel
store.openSidePanel('image-clip');
```

## How to implement your own hidden panel? [#how-to-implement-your-own-hidden-panel]

You can create custom hidden panels that don't appear in the tab bar but open based on user actions, similar to the built-in ones above.

To implement a hidden panel:

```tsx
// define the new custom section
const CustomSection = {
  name: 'custom-text',
  // use "empty" tab that will render nothing
  Tab: () => null,
  // we need observer to update component automatically on any store changes
  Panel: observer(({ store }) => {
    const text = store.selectedElements[0]?.text;
    return (
      <div>
        <InputGroup
          value={text}
          onChange={() => {
            store.selectedElements[0].set({ text: e.target.value });
          }}
        />
      </div>
    );
  }),
};

// add new section to side bar
const sections = [...DEFAULT_SECTIONS, CustomSection];

// use mobx reaction to react to selection changes
reaction(
  () => {
    const textSelected = store.selectedElements[0]?.type === 'text';
    return textSelected;
  },
  // we can use result returned from reaction
  (textSelected) => {
    if (textSelected) {
      store.openSidePanel('custom-text');
    }
  }
);

export const App = () => {
  return (
    <PolotnoContainer className="polotno-app-container">
      <SidePanelWrap>
        <SidePanel store={store} sections={sections} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} downloadButtonEnabled />
        <Workspace store={store} />
        <ZoomButtons store={store} />
      </WorkspaceWrap>
    </PolotnoContainer>
  );
};
```

For the demo, try to create a text element. As soon as it is selected, you will see a new side panel opened.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-hidden-panel" />


---

# Pexels photos
URL: https://polotno.com/docs/pexels-photos



You can use customization of Polotno's Side Panel to add your own panels with your own assets.

## How to integrate photos from Pexels.com API? [#how-to-integrate-photos-from-pexelscom-api]

First, set up your own backend proxy to the Pexels API. See the official docs: [https://www.pexels.com/api](https://www.pexels.com/api)

Example using Node.js:

```js
module.exports = async (req, res) => {
  var i = req.url.indexOf('?');
  var query = req.url.substr(i + 1);

  // if no query provided, let's return a list of curated photos
  const searchPrefix = req.query.query ? 'search/' : '/curated';

  const r = await fetch(
    `https://api.pexels.com/v1/${searchPrefix}?query=${encodeURIComponent(
      req.query.query
    )}&page=${req.query.page}&per_page=${req.query.per_page}`,
    {
      headers: {
        Authorization: 'YOUR_API_KEY_FROM_PEXELS',
      },
    }
  );

  if (r.status !== 200) {
    return res.status(r.status).send(await r.text());
  }

  let result = await r.json();

  res.status(r.status).json(result);
};
```

After creating your API endpoint, create a new Side Panel section and show it in Polotno Editor. Example section using the proxy:

```tsx
import React from 'react';
import { SearchInput } from 'polotno/primitives';
import { ImagesGrid } from 'polotno/side-panel/images-grid';
import { getImageSize, getCrop } from 'polotno/utils/image';
import { SectionTab } from 'polotno/side-panel';
import { useInfiniteAPI } from 'polotno/utils/use-api';
import { t } from 'polotno/utils/l10n';
import SiPexels from '@meronex/icons/si/SiPexels';

// this is a demo key just for that project
// (!) please don't use it in your projects
// to create your own API key please go here: https://polotno.com/login
const key = 'nFA5H9elEytDyPyvKL7T';

// use Polotno API proxy into Pexels
// WARNING: don't use on production! Use your own proxy and Pexels API key
const API = 'https://api.polotno.com/api';
const getPexelsAPI = ({ query, page }: { query: string; page: number }) =>
  `${API}/get-pexels?query=${query}&per_page=20&page=${page}&KEY=${key}`;

export const PexelsPanel = ({ store }: { store: any }) => {
  const { setQuery, loadMore, isReachingEnd, data, isLoading, error } =
    useInfiniteAPI({
      defaultQuery: '',
      getAPI: ({ page, query }) => getPexelsAPI({ page, query }),
      getSize: (lastResponse) => lastResponse.total_results / lastResponse.per_page,
    });

  return (
    <div style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
      <SearchInput
        placeholder={t('sidePanel.searchPlaceholder')}
        onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
          setQuery(e.target.value);
        }}
        style={{ marginBottom: '20px' }}
      />
      <p style={{ textAlign: 'center' }}>
        Photos by{' '}
        <a href="https://www.pexels.com/" target="_blank" rel="noreferrer">
          Pexels
        </a>
      </p>
      <ImagesGrid
        images={data?.map((item: any) => item.photos).flat().filter(Boolean)}
        getPreview={(image: any) => image.src.medium}
        onSelect={async (image: any, pos?: { x: number; y: number }, element?: any) => {
          // get url of image
          const src = image.src.large;

          // if we dropped image into svg element, apply mask for it
          if (element && element.type === 'svg' && element.contentEditable) {
            element.set({ maskSrc: src });
            return;
          }

          // get image size
          const { width, height } = await getImageSize(src);

          // if dropped into another image, recalculate crop and apply new image
          if (element && element.type === 'image' && element.contentEditable) {
            const crop = getCrop(element, { width, height });
            element.set({ src, ...crop });
            return;
          }

          // otherwise create new image
          const x = (pos?.x || store.width / 2) - width / 2;
          const y = (pos?.y || store.height / 2) - height / 2;
          store.activePage?.addElement({
            type: 'image',
            src,
            width,
            height,
            x,
            y,
          });
        }}
        isLoading={isLoading}
        error={error}
        loadMore={!isReachingEnd && loadMore}
        getCredit={(image: any) => (
          <span>
            Photo by{' '}
            <a href={image.photographer_url} target="_blank" rel="noreferrer">
              {image.photographer}
            </a>{' '}
            on{' '}
            <a
              href="https://pexels.com/?utm_source=polotno&utm_medium=referral"
              target="_blank"
              rel="noreferrer"
            >
              Pexels
            </a>
          </span>
        )}
      />
    </div>
  );
};

// define the new custom section
export const PexelsSection = {
  name: 'pexels',
  Tab: (props: any) => (
    <SectionTab name="Pexels" {...props}>
      <SiPexels />
    </SectionTab>
  ),
  // we need observer to update component automatically on any store changes
  Panel: PexelsPanel,
};
```

When you created a new section in the side panel, pass it into `<SidePanel />`:

```tsx
import { SidePanel, DEFAULT_SECTIONS } from 'polotno/side-panel';
import { PexelsSection } from './pexels-section';

const sections = [PexelsSection, ...DEFAULT_SECTIONS];

// in render:
<SidePanel store={store} sections={sections} defaultSection="pexels" />
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-pexels" />


---

# Remove side panel
URL: https://polotno.com/docs/remove-side-panel



## How to remove the side panel? [#how-to-remove-the-side-panel]

You can control side panels in Polotno SDK. If you don't need some of the panels, remove them by name.

```tsx
import { PolotnoContainer, SidePanelWrap, WorkspaceWrap } from 'polotno';
import { SidePanel, DEFAULT_SECTIONS } from 'polotno/side-panel';
import { Toolbar } from 'polotno/toolbar/toolbar';
import { ZoomButtons } from 'polotno/toolbar/zoom-buttons';
import { PagesTimeline } from 'polotno/pages-timeline';
import { Workspace } from 'polotno/canvas/workspace';

// first you can log all sections into console to see what sections are defined
const names = DEFAULT_SECTIONS.map((section) => section.name);
console.log(names);

// if you don't need a specific section, remove it by its name
// for example, remove the upload section
const sections = DEFAULT_SECTIONS.filter((section) => section.name !== 'upload');

export const App = () => {
  return (
    <PolotnoContainer className="polotno-app-container">
      <SidePanelWrap>
        <SidePanel store={store} sections={sections} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} downloadButtonEnabled />
        <Workspace store={store} />
        <ZoomButtons store={store} />
        <PagesTimeline store={store} />
      </WorkspaceWrap>
    </PolotnoContainer>
  );
};
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-remove-side-panel" />


---

# Side Panel overview
URL: https://polotno.com/docs/side-panel-overview



**SidePanel** provides a default set of components for adding new elements to the canvas, changing page sizes, and more.

```tsx
import { SidePanel } from 'polotno/side-panel';

const MyPanel = () => {
  return (
    <div>
      <SidePanel store={store} />
    </div>
  );
};
```

The `SidePanel` will automatically use the full width and height of its parent; you don't have to manually adjust its size. Set the size of the parent `div` with CSS.

## How to hide the side panel on initial load? [#how-to-hide-the-side-panel-on-initial-load]

Use the `defaultSection` prop to control which section is open when the component first mounts. Pass an empty string to start with the panel closed:

```tsx
<SidePanel store={store} defaultSection="" />
```

**Note:** `store.openSidePanel('')` will not work for this purpose because it is called before `<SidePanel>` mounts, and the component overrides it with its default on mount.

## How to customize side panel tabs? [#how-to-customize-side-panel-tabs]

You can pass the `sections` property to the `<SidePanel />` component to specify all available tabs manually.

Default UI:

```tsx
import { SidePanel, DEFAULT_SECTIONS } from 'polotno/side-panel';

const MyPanel = () => {
  return (
    <div>
      <SidePanel store={store} sections={DEFAULT_SECTIONS} />
    </div>
  );
};
```

Define sections manually:

```tsx
import { observer } from 'mobx-react-lite';
import { SidePanel } from 'polotno/side-panel';
// import existing section
import { TextSection } from 'polotno/side-panel';

// import default tab component
import { SectionTab } from 'polotno/side-panel';
// import our own icon
import FaShapes from '@meronex/icons/fa/FaShapes';

// define the new custom section
const CustomSection = {
  name: 'custom',
  Tab: (props) => (
    <SectionTab name="Custom" {...props}>
      <FaShapes />
    </SectionTab>
  ),
  // we need observer to update component automatically on any store changes
  Panel: observer(({ store }) => {
    return (
      <div>
        <p>Here we will define our own custom tab.</p>
        <p>Elements on the current page: {store.activePage?.children.length}</p>
      </div>
    );
  }),
};

// we will have just two sections
const sections = [CustomSection, TextSection];

const CustomSidePanel = () => {
  return <SidePanel store={store} sections={sections} defaultSection="custom" />;
};
```

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-custom-side-panel" />

## Related Pages [#related-pages]

* [Custom Images Panel](/docs/custom-images-panel) - Load images from your own backend
* [Pexels Photos](/docs/pexels-photos) - Integrate Pexels API for stock photos
* [Upload Panel](/docs/upload-panel) - Customize file upload functionality
* [Background Side Panel Customization](/docs/background-side-panel-customization) - Customize background selection panel
* [Hidden Panels](/docs/hidden-panels) - Hide specific default panels
* [Remove Side Panel](/docs/remove-side-panel) - Remove the side panel entirely


---

# Upload panel
URL: https://polotno.com/docs/upload-panel



**Important:** the default upload panel has the most basic setup. It can't keep uploaded images across user sessions, and it doesn't return images to the backend. Instead it injects images as base64 string directly into the design, which may affect performance. It is highly recommended to use your own version of an upload panel.

## How to implement upload section? [#how-to-implement-upload-section]

Upload section may work very similar to the [Images Section](/docs/custom-images-panel). You just need to implement several API endpoints on your backend to allow:

1. Loading list of user images
2. Uploading new image
3. Deleting image

The example below doesn't use a real server to implement this function. It just uses local storage to store images. But you can use it as a starting point.

## Live demo [#live-demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-upload-section" />


---

# Utils API
URL: https://polotno.com/docs/utils-api



When building a custom side panel feel free to choose any React components you prefer. You can build your own one from scratch as well.

Displaying a grid of media previews is a common requirement inside custom side panels. You can reuse `<ImagesGrid />` to cover layout, lazy loading, and drag-and-drop without rebuilding those behaviors yourself.

## ImagesGrid component [#imagesgrid-component]

Use `<ImagesGrid />` to render any collection as clickable previews. You provide the data array and the preview accessor, and the component renders responsive columns, shows loading states, and wires drag events into the canvas. Items can be clicked or dragged, letting you decide how to create or update elements in the workspace.

* Render arbitrary data as image thumbnails with lazy loading
* Trigger canvas updates on click or drag
* Request more data automatically when the list runs low

### Basic usage [#basic-usage]

Start with a minimal panel that passes the image collection, a preview getter, and an `onSelect` callback. The handler receives the original item plus optional drop coordinates and the element that was targeted on the canvas.

```tsx
import { ImagesGrid } from 'polotno/side-panel/images-grid';

const images = [
  { id: '1', url: 'https://picsum.photos/seed/1/600/800' },
  { id: '2', url: 'https://picsum.photos/seed/2/600/800' },
];

export const TemplatesPanel = ({ store }) => (
  <ImagesGrid
    images={images}
    getPreview={(item) => item.url}
    getAlt={(item) => item.alt}
    onSelect={(image, pos, element) => {
      const width = 200;
      const height = 200;
      const x = (pos?.x ?? store.width / 2) - width / 2;
      const y = (pos?.y ?? store.height / 2) - height / 2;

      store.activePage?.addElement({
        type: 'image',
        src: image.url,
        width,
        height,
        x,
        y,
      });
    }}
    isLoading={false}
  />
);
```

> **Tip**: The component calls your `onSelect` handler for both click and drop interactions. Use the optional `element` argument to detect when a user drops onto an existing node and branch your logic.

### Infinite loading [#infinite-loading]

`loadMore` fires when the scroll position approaches the bottom or when the grid finishes rendering but still cannot fill the viewport. Pair it with `isLoading` and optional API helpers to keep results flowing.

```tsx
import { useInfiniteAPI } from 'polotno/utils/use-api';

const { data, isLoading, loadMore } = useInfiniteAPI({
  getAPI: ({ page }) => `https://example.com/images?page=${page}`,
  getSize: (firstResult) => firstResult.total_pages,
});

const images = data?.flatMap((page) => page.results) ?? [];

<ImagesGrid
  images={images}
  getPreview={(item) => item.src}
  getAlt={(item) => item.alt} // optional
  onSelect={(image) => addImageToStore(image)}
  isLoading={isLoading}
  loadMore={loadMore}
  hideNoResults={false}
/>;
```

> **Tip**: `loadMore` receives no arguments, so keep pagination state outside the component. Call `loadMore` only when `isLoading` is `false` to avoid overlapping requests.

### Drag and drop behavior [#drag-and-drop-behavior]

Dragging an item registers a temporary DOM drop listener through Polotno’s `registerNextDomDrop`. You receive canvas coordinates and the optional target element, enabling both “create new” and “replace existing” flows with a single handler. The component clears the listener after each drag cycle so you do not need manual cleanup.

> **Note**: If you build a custom drop zone outside of the canvas, call `registerNextDomDrop(null)` when the drag ends to avoid dangling handlers.

### Styling options [#styling-options]

Control the layout with `rowsNumber` (columns), explicit `itemHeight`, and the `shadowEnabled` flag. Every image is responsive by default, and credits can be shown via `getCredit` to comply with provider requirements.

> **Note**: On mobile breakpoints the credit overlay stays visible, so keep the element short and avoid interactive children.

### Prop reference [#prop-reference]

| Prop                | Type                                                 | Default       | Description                                                                              |                                                                                             |             |                                                                                      |
| ------------------- | ---------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------ |
| `images`            | \`ImageType\[]                                       | undefined\`   | `[]`                                                                                     | Collection rendered as thumbnails; pass an empty array while loading to keep layout stable. |             |                                                                                      |
| `getPreview`        | `(image: ImageType) => string`                       | —             | Returns the image URL used for the thumbnail and drag payload.                           |                                                                                             |             |                                                                                      |
| `getAlt`            | `(image: ImageType) => string`                       | `undefined`   | Returns the image alt text used for the thumbnail.                                       |                                                                                             |             |                                                                                      |
| `onSelect`          | `(image: ImageType, pos?, element?, event?) => void` | —             | Handles both click and drop; receive drop coordinates and target element when available. |                                                                                             |             |                                                                                      |
| `isLoading`         | `boolean`                                            | `false`       | Shows the spinner at the end of each column and blocks automatic `loadMore` triggers.    |                                                                                             |             |                                                                                      |
| `loadMore`          | \`() => void                                         | false         | null                                                                                     | undefined\`                                                                                 | `undefined` | Called near the bottom of the scroll area or when the grid cannot fill the viewport. |
| `getCredit`         | `(image: ImageType) => React.ReactNode`              | `undefined`   | Renders a credit overlay over the image; hidden on desktop hover until active.           |                                                                                             |             |                                                                                      |
| `getImageClassName` | `(image: ImageType) => string`                       | `undefined`   | Adds custom class names to the `<img>` tag for further styling.                          |                                                                                             |             |                                                                                      |
| `rowsNumber`        | `number`                                             | `2`           | Sets the number of columns; the grid distributes items evenly by index.                  |                                                                                             |             |                                                                                      |
| `crossOrigin`       | `string`                                             | `'anonymous'` | Controls the `crossOrigin` attribute on the `<img>` tag to support canvas exports.       |                                                                                             |             |                                                                                      |
| `shadowEnabled`     | `boolean`                                            | `true`        | Toggles the drop shadow around image containers.                                         |                                                                                             |             |                                                                                      |
| `itemHeight`        | \`number                                             | string\`      | `'auto'`                                                                                 | Fixes thumbnail height while preserving width; defaults to auto sizing.                     |             |                                                                                      |
| `error`             | `any`                                                | `undefined`   | When truthy, the grid shows the localized error message instead of thumbnails.           |                                                                                             |             |                                                                                      |
| `hideNoResults`     | `boolean`                                            | `false`       | Suppresses the default “no results” label when the data array is empty.                  |                                                                                             |             |                                                                                      |

## How to use `useInfiniteAPI` hook? [#how-to-use-useinfiniteapi-hook]

In scenarios where an API is called to display a list of images within a side panel grid, various React tools are at your disposal. This includes utilizing fetch methods within hooks or leveraging any suitable library for the task. Additionally, Polotno provides the `useInfiniteAPI` hook as a convenient option. The `useInfiniteAPI` hook serves as a wrapper around the [swr](https://swr.vercel.app/) library, simplifying the process of fetching data.

```ts
import { useInfiniteAPI } from 'polotno/utils/use-api';

export const SidePanel = () => {
  const { data, isLoading, loadMore, isReachingEnd, hasMore, reset, error } = useInfiniteAPI({
    // a function that will return a URL to request
    getAPI: ({ page, query }) => `https://example.com/api?page=${page}&query=${query}`,
    // default search query for the first call call
    defaultQuery: '',
    // timeout before making a new call when you change search query, useful for debouncing
    timeout: 500,
    // a function that should return number of pages available from the first API response
    // usually API response has a "totalPages", "size" or other field that tells you how many pages are available
    getSize: (firstResult) => firstResult.total_pages,
    // a function to make an API request
    // here is example of default fetch function
    // you can customize it to add for example headers
    fetchFunc: (url) => fetch(url).then((r) => r.json()),
  });

  // data - is an array of responses from the API
  // each item in the array corresponds to a page

  // loadMore - function to be called when you want to request for more data
  // ImagesGrid will use it when you scrape the bottom of the list

  // isReachingEnd - true if you are at the end of the list

  // hasMore - true if you can request for more data
  // reset - function to be called when you want to reset the list
  // error - error object if something went wrong
};
```

## How to drop elements from side panel into workspace? [#how-to-drop-elements-from-side-panel-into-workspace]

If you prefer not to use `<ImagesGrid />` component, you will have to handle drag\&drop of DOM elements implementation. However, Polotno has some tools to listen to drop events on the workspace. You can use this:

```tsx
import { unstable_registerNextDomDrop } from 'polotno/config';

// then in your components inside side panel you can do something like this:
<img
  draggable
  src={url}
  onDragStart={() => {
    registerNextDomDrop((pos, element) => {
      // "pos" - is relative mouse position of drop
      // "element" - is element from your store in case when DOM object is dropped on another element

      // you can just create new element on drop position
      // or you can update existing element
      // for example we can drop image from side panel into existing 'image' element in the workspace
      if (element && element.type === 'image') {
        // you can update any property you want, src, clipSrc, border, etc
        element.set({ src: url });
        return;
      }
      // or we can just create a new element
      store.activePage.addElement({
        type: 'image',
        src: url,
        x: pos.x,
        y: pos.y,
        width: 100,
        height: 100,
      });
    });
  }}
  onDragEnd={() => {
    registerNextDomDrop(null);
  }}
/>;
```


---

# Sandpack Demo Component
URL: https://polotno.com/docs/components/_sandpack-demo



## Sandpack Demo Component [#sandpack-demo-component]

The `SandpackDemo` component allows you to create interactive code sandboxes with Polotno pre-configured. It's perfect for demonstrating code examples in your documentation.

## Basic Usage [#basic-usage]

Here's a basic Polotno editor:

<SandpackDemo />

## Custom Dependencies [#custom-dependencies]

You can add custom dependencies beyond the default ones:

<SandpackDemo
  dependencies="{
  &#x22;lodash&#x22;: &#x22;^4.17.21&#x22;,
  &#x22;date-fns&#x22;: &#x22;^2.29.3&#x22;
}"
/>

## Custom Code Example [#custom-code-example]

You can provide custom files to show specific examples:

<SandpackDemo
  files="{
  &#x22;/App.js&#x22;: `import React from 'react';
import { PolotnoContainer, SidePanelWrap, WorkspaceWrap } from 'polotno';
import { Workspace } from 'polotno/canvas/workspace';
import { SidePanel } from 'polotno/side-panel';
import { Toolbar } from 'polotno/toolbar/toolbar';
import { ZoomButtons } from 'polotno/toolbar/zoom-buttons';
import { createStore } from 'polotno/model/store';

const store = createStore({
key: 'nFA5H9elEytDyPyvKL7T',
});

// Add a default template
store.addPage();

export default function App() {
return (
  <PolotnoContainer style={{ width: '100vw', height: '100vh' }}>
    <SidePanelWrap>
      <SidePanel store={store} />
    </SidePanelWrap>
    <WorkspaceWrap>
      <Toolbar store={store} downloadButtonEnabled />
      <Workspace store={store} />
      <ZoomButtons store={store} />
    </WorkspaceWrap>
  </PolotnoContainer>
);
}`
}"
/>

## Component Props [#component-props]

The `SandpackDemo` component accepts the following props:

### `dependencies` [#dependencies]

* **Type**: `Record<string, string>`
* **Default**: `{}`
* **Description**: Custom dependencies to include alongside the default ones (polotno, react, react-dom, react-scripts)

### `files` [#files]

* **Type**: `Record<string, string>`
* **Default**: `{}`
* **Description**: Custom files to include in the sandbox. If not provided, uses a default App.js with basic Polotno setup

### `options` [#options]

* **Type**: `object`
* **Default**: `{}`
* **Description**: Custom options for the Sandpack instance (showNavigator, showTabs, etc.)

### `height` [#height]

* **Type**: `number | string`
* **Default**: `400`
* **Description**: Height of the sandbox editor

### `theme` [#theme]

* **Type**: `'light' | 'dark' | 'auto'`
* **Default**: `'light'`
* **Description**: Theme for the sandbox

## Advanced Example [#advanced-example]

<SandpackDemo
  height="500"
  theme="light"
  dependencies="{
  &#x22;mobx&#x22;: &#x22;^6.6.0&#x22;,
  &#x22;mobx-react-lite&#x22;: &#x22;^3.4.0&#x22;
}"
  options="{
  showLineNumbers: true,
  showInlineErrors: true,
  wrapContent: true
}"
  files="{
  &#x22;/App.js&#x22;: `import React from 'react';
import { PolotnoContainer, SidePanelWrap, WorkspaceWrap } from 'polotno';
import { Workspace } from 'polotno/canvas/workspace';
import { SidePanel } from 'polotno/side-panel';
import { Toolbar } from 'polotno/toolbar/toolbar';
import { ZoomButtons } from 'polotno/toolbar/zoom-buttons';
import { createStore } from 'polotno/model/store';

const store = createStore({
key: 'nFA5H9elEytDyPyvKL7T',
});

// Create a custom page with some elements
store.addPage();
store.activePage.addElement({
type: 'text',
text: 'Welcome to Polotno!',
x: 50,
y: 50,
fontSize: 32,
fill: '#2563eb',
fontWeight: 'bold',
});

store.activePage.addElement({
type: 'text',
text: 'This is an interactive demo',
x: 50,
y: 100,
fontSize: 16,
fill: '#64748b',
});

export default function App() {
return (
  <PolotnoContainer style={{ width: '100vw', height: '100vh' }}>
    <SidePanelWrap>
      <SidePanel store={store} />
    </SidePanelWrap>
    <WorkspaceWrap>
      <Toolbar store={store} downloadButtonEnabled />
      <Workspace store={store} />
      <ZoomButtons store={store} />
    </WorkspaceWrap>
  </PolotnoContainer>
);
}`,
  &#x22;/styles.css&#x22;: `body {
margin: 0;
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
  'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
  sans-serif;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}

* {
box-sizing: border-box;
}`
}"
/>


---

# Brand Kit Side Panel
URL: https://polotno.com/docs/components/brand-kit



The Brand Kit side panel is a tool that allows you to manage your brand kit. It includes a color palette, typography, and assets.
We recommend to read the [Overview](./overview) page to understand how to use the Brand Kit side panel.

## Installation [#installation]

```bash
npx shadcn@latest add http://registry.polotno.com:/r/brand-kit.json --path ./src/components/side-panel/brand-kit/
```

After installatin you will see a new files in `/src/components/side-panel/brand-kit/`
You can change setup location as you want.

## Usage [#usage]

```tsx
// make sure to change the path to the correct location
import { BrandKitSection } from './components/side-panel/brand-kit/brand-kit-panel';
import { SidePanel, DEFAULT_SECTIONS } from 'polotno/side-panel';


const sections = [...DEFAULT_SECTIONS, BrandKitSection];

// in sidepanel render:
<SidePanel sections={sections} />
```

## Demo [#demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-brand-kit" />


---

# Components Overview
URL: https://polotno.com/docs/components/overview



## Open components — own and customize [#open-components--own-and-customize]

These components are installed as source files into your repository. You commit them, edit them, and adapt them to your product. They’re designed to be customized — markup, styles, and behavior are all yours.

Note: we still publish npm components for convenience. These “open components” are an additional option when you want full control and easy customization.

## Add components [#add-components]

Use our CLI to add components; it copies files into your repo (commonly under `./src/components/`).

```bash
# add a few UI components
npx shadcn@latest add http://registry.polotno.com:/r/qr-code.json
```

## Customize [#customize]

* Edit the component files directly to match your UX, API and business logic
* Because it’s your code, refactors and reviews are straightforward

## Update or remove [#update-or-remove]

* To update, add the component again and compare diffs in Git (cherry‑pick what you need)
* To remove, delete the files and related imports — no special uninstall


---

# QR Code Side Panel
URL: https://polotno.com/docs/components/qr-code



## Installatin [#installatin]

<Tabs items="['CLI', 'Manual']">
  <Tab value="CLI">
    ```bash
    npx shadcn@latest add http://registry.polotno.com:/r/qr-code.json --path ./src/components/side-panel/qr-code.tsx
    ```

    After installatin you will see a new create file in `/src/components/side-panel/qr-code.tsx`.
    You can change setup location as you want.
  </Tab>

  <Tab value="Manual">
    ```bash
    npx install qr-code @meronex/icons
    ```

    Copy and paste the following code into your project.

    <CodeFromFile src="src/components/side-panel/qr-code.tsx" title="examples/components/side-panel/qr-code.tsx" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { QrSection } from './side-panel/qr-code'; // make sure to change the path to the correct location
import { SidePanel, DEFAULT_SECTIONS } from 'polotno/side-panel';


const sections = [...DEFAULT_SECTIONS, QrSection];

<SidePanel sections={sections} />
```

## Demo [#demo]

<Sandbox github="polotno-project/polotno-docs/tree/main/examples/polotno-qr-codes" />


---

# Animation
URL: https://polotno.com/docs/schema/animation



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property   | Type                              | Description                                         |
| ---------- | --------------------------------- | --------------------------------------------------- |
| `delay`    | `number`                          | Delay before the animation starts, in milliseconds. |
| `duration` | `number`                          | Animation duration in milliseconds.                 |
| `enabled`  | `boolean`                         | Whether the animation is enabled.                   |
| `type`     | `"enter"` \| `"exit"` \| `"loop"` | Animation phase.                                    |
| `name`     | `string`                          | Animation name identifier.                          |
| `data`     | `unknown`                         | Animation-specific data.                            |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "delay": {
      "default": 0,
      "description": "Delay before the animation starts, in milliseconds.",
      "type": "number"
    },
    "duration": {
      "default": 500,
      "description": "Animation duration in milliseconds.",
      "type": "number"
    },
    "enabled": {
      "default": true,
      "description": "Whether the animation is enabled.",
      "type": "boolean"
    },
    "type": {
      "type": "string",
      "enum": [
        "enter",
        "exit",
        "loop"
      ],
      "description": "Animation phase."
    },
    "name": {
      "default": "none",
      "description": "Animation name identifier.",
      "type": "string"
    },
    "data": {
      "default": {},
      "description": "Animation-specific data."
    }
  },
  "required": [
    "type"
  ]
}
```

## Related Definitions [#related-definitions]

*No related definitions found.*


---

# Audio
URL: https://polotno.com/docs/schema/audio



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property    | Type      | Description                             |
| ----------- | --------- | --------------------------------------- |
| `id`        | `string`  | Unique identifier for the audio track.  |
| `src`       | `string`  | URL or data URI of the audio file.      |
| `duration`  | `number`  | Duration in milliseconds.               |
| `startTime` | `number`  | Start offset (0-1).                     |
| `endTime`   | `number`  | End offset (0-1).                       |
| `volume`    | `number`  | Volume level (0-1).                     |
| `delay`     | `number`  | Delay before playing, in milliseconds.  |
| `speed`     | `number`  | Playback speed multiplier (1 = normal). |
| `custom`    | `unknown` | *No description provided*               |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the audio track."
    },
    "src": {
      "default": "",
      "description": "URL or data URI of the audio file.",
      "type": "string"
    },
    "duration": {
      "default": 0,
      "description": "Duration in milliseconds.",
      "type": "number"
    },
    "startTime": {
      "default": 0,
      "description": "Start offset (0-1).",
      "type": "number"
    },
    "endTime": {
      "default": 1,
      "description": "End offset (0-1).",
      "type": "number"
    },
    "volume": {
      "default": 1,
      "description": "Volume level (0-1).",
      "type": "number"
    },
    "delay": {
      "default": 0,
      "description": "Delay before playing, in milliseconds.",
      "type": "number"
    },
    "speed": {
      "default": 1,
      "description": "Playback speed multiplier (1 = normal).",
      "type": "number"
    },
    "custom": {}
  },
  "required": [
    "id"
  ]
}
```

## Related Definitions [#related-definitions]

*No related definitions found.*


---

# BorderSide
URL: https://polotno.com/docs/schema/border-side



Top border override for this cell.

## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property | Type                                              | Description                           |
| -------- | ------------------------------------------------- | ------------------------------------- |
| `color`  | `string`                                          | Border color for this side.           |
| `width`  | `number`                                          | Border width in pixels for this side. |
| `style`  | `"solid"` \| `"dashed"` \| `"dotted"` \| `"none"` | Border style for this side.           |

## JSON Schema [#json-schema]

```json
{
  "description": "Top border override for this cell.",
  "type": "object",
  "properties": {
    "color": {
      "description": "Border color for this side.",
      "type": "string"
    },
    "width": {
      "description": "Border width in pixels for this side.",
      "type": "number"
    },
    "style": {
      "description": "Border style for this side.",
      "type": "string",
      "enum": [
        "solid",
        "dashed",
        "dotted",
        "none"
      ]
    }
  }
}
```

## Related Definitions [#related-definitions]

*No related definitions found.*


---

# CellBorders
URL: https://polotno.com/docs/schema/cell-borders



Per-side border overrides for this cell.

## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property | Type                          | Description                           |
| -------- | ----------------------------- | ------------------------------------- |
| `top`    | [`BorderSide`](./border-side) | Top border override for this cell.    |
| `right`  | [`BorderSide`](./border-side) | Right border override for this cell.  |
| `bottom` | [`BorderSide`](./border-side) | Bottom border override for this cell. |
| `left`   | [`BorderSide`](./border-side) | Left border override for this cell.   |

## JSON Schema [#json-schema]

```json
{
  "description": "Per-side border overrides for this cell.",
  "type": "object",
  "properties": {
    "top": {
      "description": "Top border override for this cell.",
      "type": "object",
      "properties": {
        "color": {
          "description": "Border color for this side.",
          "type": "string"
        },
        "width": {
          "description": "Border width in pixels for this side.",
          "type": "number"
        },
        "style": {
          "description": "Border style for this side.",
          "type": "string",
          "enum": [
            "solid",
            "dashed",
            "dotted",
            "none"
          ]
        }
      }
    },
    "right": {
      "description": "Right border override for this cell.",
      "type": "object",
      "properties": {
        "color": {
          "description": "Border color for this side.",
          "type": "string"
        },
        "width": {
          "description": "Border width in pixels for this side.",
          "type": "number"
        },
        "style": {
          "description": "Border style for this side.",
          "type": "string",
          "enum": [
            "solid",
            "dashed",
            "dotted",
            "none"
          ]
        }
      }
    },
    "bottom": {
      "description": "Bottom border override for this cell.",
      "type": "object",
      "properties": {
        "color": {
          "description": "Border color for this side.",
          "type": "string"
        },
        "width": {
          "description": "Border width in pixels for this side.",
          "type": "number"
        },
        "style": {
          "description": "Border style for this side.",
          "type": "string",
          "enum": [
            "solid",
            "dashed",
            "dotted",
            "none"
          ]
        }
      }
    },
    "left": {
      "description": "Left border override for this cell.",
      "type": "object",
      "properties": {
        "color": {
          "description": "Border color for this side.",
          "type": "string"
        },
        "width": {
          "description": "Border width in pixels for this side.",
          "type": "number"
        },
        "style": {
          "description": "Border style for this side.",
          "type": "string",
          "enum": [
            "solid",
            "dashed",
            "dotted",
            "none"
          ]
        }
      }
    }
  }
}
```

## Related Definitions [#related-definitions]

* [BorderSide](./border-side)


---

# Element
URL: https://polotno.com/docs/schema/element



## Type Information [#type-information]

**Base Type:** `union`

## Variants [#variants]

A value of this type is one of:

* [TextElement](./text-element)
* [ImageElement](./image-element)
* [SVGElement](./svg-element)
* [LineElement](./line-element)
* [FigureElement](./figure-element)
* [GifElement](./gif-element)
* [VideoElement](./video-element)
* [TableElement](./table-element)
* [GroupElement](./group-element)

## JSON Schema [#json-schema]

```json
{
  "oneOf": [
    {
      "type": "text"
    },
    {
      "type": "image"
    },
    {
      "type": "svg"
    },
    {
      "type": "line"
    },
    {
      "type": "figure"
    },
    {
      "type": "gif"
    },
    {
      "type": "video"
    },
    {
      "type": "table"
    },
    {
      "type": "group"
    }
  ]
}
```

## Related Definitions [#related-definitions]

* [Animation](./animation)
* [TableCell](./table-cell)
* [CellBorders](./cell-borders)
* [BorderSide](./border-side)


---

# FigureElement
URL: https://polotno.com/docs/schema/figure-element



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property            | Type                               | Description                                   |
| ------------------- | ---------------------------------- | --------------------------------------------- |
| `id`                | `string`                           | Unique identifier for the element.            |
| `type`              | `"figure"`                         | *No description provided*                     |
| `name`              | `string`                           | Display name for the element.                 |
| `custom`            | `unknown`                          | Custom data attached to the element.          |
| `x`                 | `number`                           | X position in pixels.                         |
| `y`                 | `number`                           | Y position in pixels.                         |
| `width`             | `number`                           | Width in pixels.                              |
| `height`            | `number`                           | Height in pixels.                             |
| `rotation`          | `number`                           | Rotation angle in degrees.                    |
| `opacity`           | `number`                           | Opacity level (0-1).                          |
| `animations`        | Array\<[`Animation`](./animation)> | Animation configurations.                     |
| `blurEnabled`       | `boolean`                          | Whether blur effect is enabled.               |
| `blurRadius`        | `number`                           | Blur radius in pixels.                        |
| `brightnessEnabled` | `boolean`                          | Whether brightness effect is enabled.         |
| `brightness`        | `number`                           | Brightness level (-1 to 1).                   |
| `sepiaEnabled`      | `boolean`                          | Whether sepia effect is enabled.              |
| `grayscaleEnabled`  | `boolean`                          | Whether grayscale effect is enabled.          |
| `filters`           | `object`                           | Applied image filters keyed by filter name.   |
| `shadowEnabled`     | `boolean`                          | Whether shadow is enabled.                    |
| `shadowBlur`        | `number`                           | Shadow blur radius in pixels.                 |
| `shadowOffsetX`     | `number`                           | Shadow horizontal offset in pixels.           |
| `shadowOffsetY`     | `number`                           | Shadow vertical offset in pixels.             |
| `shadowColor`       | `string`                           | Shadow color.                                 |
| `shadowOpacity`     | `number`                           | Shadow opacity (0-1).                         |
| `visible`           | `boolean`                          | Whether the element is visible.               |
| `draggable`         | `boolean`                          | Whether the element can be dragged.           |
| `resizable`         | `boolean`                          | Whether the element can be resized.           |
| `selectable`        | `boolean`                          | Whether the element can be selected.          |
| `removable`         | `boolean`                          | Whether the element can be removed.           |
| `contentEditable`   | `boolean`                          | Whether the element content can be edited.    |
| `styleEditable`     | `boolean`                          | Whether the element style can be edited.      |
| `alwaysOnTop`       | `boolean`                          | Whether the element stays on top of others.   |
| `showInExport`      | `boolean`                          | Whether the element appears in exports.       |
| `subType`           | `string`                           | Figure subtype: rect, ellipse, triangle, etc. |
| `fill`              | `string`                           | Fill color.                                   |
| `dash`              | Array\<`number`>                   | Dash pattern array.                           |
| `strokeWidth`       | `number`                           | *No description provided*                     |
| `stroke`            | `string`                           | *No description provided*                     |
| `cornerRadius`      | `number`                           | *No description provided*                     |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the element."
    },
    "type": {
      "type": "string",
      "const": "figure"
    },
    "name": {
      "default": "",
      "description": "Display name for the element.",
      "type": "string"
    },
    "custom": {
      "description": "Custom data attached to the element."
    },
    "x": {
      "default": 0,
      "description": "X position in pixels.",
      "type": "number"
    },
    "y": {
      "default": 0,
      "description": "Y position in pixels.",
      "type": "number"
    },
    "width": {
      "default": 100,
      "description": "Width in pixels.",
      "type": "number"
    },
    "height": {
      "default": 100,
      "description": "Height in pixels.",
      "type": "number"
    },
    "rotation": {
      "default": 0,
      "description": "Rotation angle in degrees.",
      "type": "number"
    },
    "opacity": {
      "default": 1,
      "description": "Opacity level (0-1).",
      "type": "number"
    },
    "animations": {
      "default": [],
      "description": "Animation configurations.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "delay": {
            "default": 0,
            "description": "Delay before the animation starts, in milliseconds.",
            "type": "number"
          },
          "duration": {
            "default": 500,
            "description": "Animation duration in milliseconds.",
            "type": "number"
          },
          "enabled": {
            "default": true,
            "description": "Whether the animation is enabled.",
            "type": "boolean"
          },
          "type": {
            "type": "string",
            "enum": [
              "enter",
              "exit",
              "loop"
            ],
            "description": "Animation phase."
          },
          "name": {
            "default": "none",
            "description": "Animation name identifier.",
            "type": "string"
          },
          "data": {
            "default": {},
            "description": "Animation-specific data."
          }
        },
        "required": [
          "type"
        ]
      }
    },
    "blurEnabled": {
      "default": false,
      "description": "Whether blur effect is enabled.",
      "type": "boolean"
    },
    "blurRadius": {
      "default": 10,
      "description": "Blur radius in pixels.",
      "type": "number"
    },
    "brightnessEnabled": {
      "default": false,
      "description": "Whether brightness effect is enabled.",
      "type": "boolean"
    },
    "brightness": {
      "default": 0,
      "description": "Brightness level (-1 to 1).",
      "type": "number"
    },
    "sepiaEnabled": {
      "default": false,
      "description": "Whether sepia effect is enabled.",
      "type": "boolean"
    },
    "grayscaleEnabled": {
      "default": false,
      "description": "Whether grayscale effect is enabled.",
      "type": "boolean"
    },
    "filters": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "intensity": {
            "default": 1,
            "description": "Filter intensity (-1 to 1).",
            "type": "number"
          }
        }
      },
      "description": "Applied image filters keyed by filter name."
    },
    "shadowEnabled": {
      "default": false,
      "description": "Whether shadow is enabled.",
      "type": "boolean"
    },
    "shadowBlur": {
      "default": 5,
      "description": "Shadow blur radius in pixels.",
      "type": "number"
    },
    "shadowOffsetX": {
      "default": 0,
      "description": "Shadow horizontal offset in pixels.",
      "type": "number"
    },
    "shadowOffsetY": {
      "default": 0,
      "description": "Shadow vertical offset in pixels.",
      "type": "number"
    },
    "shadowColor": {
      "default": "black",
      "description": "Shadow color.",
      "type": "string"
    },
    "shadowOpacity": {
      "default": 1,
      "description": "Shadow opacity (0-1).",
      "type": "number"
    },
    "visible": {
      "default": true,
      "description": "Whether the element is visible.",
      "type": "boolean"
    },
    "draggable": {
      "default": true,
      "description": "Whether the element can be dragged.",
      "type": "boolean"
    },
    "resizable": {
      "default": true,
      "description": "Whether the element can be resized.",
      "type": "boolean"
    },
    "selectable": {
      "default": true,
      "description": "Whether the element can be selected.",
      "type": "boolean"
    },
    "removable": {
      "default": true,
      "description": "Whether the element can be removed.",
      "type": "boolean"
    },
    "contentEditable": {
      "default": true,
      "description": "Whether the element content can be edited.",
      "type": "boolean"
    },
    "styleEditable": {
      "default": true,
      "description": "Whether the element style can be edited.",
      "type": "boolean"
    },
    "alwaysOnTop": {
      "default": false,
      "description": "Whether the element stays on top of others.",
      "type": "boolean"
    },
    "showInExport": {
      "default": true,
      "description": "Whether the element appears in exports.",
      "type": "boolean"
    },
    "subType": {
      "default": "rect",
      "description": "Figure subtype: rect, ellipse, triangle, etc.",
      "type": "string"
    },
    "fill": {
      "default": "rgb(0, 161, 255)",
      "description": "Fill color.",
      "type": "string"
    },
    "dash": {
      "default": [],
      "description": "Dash pattern array.",
      "type": "array",
      "items": {
        "type": "number"
      }
    },
    "strokeWidth": {
      "default": 0,
      "type": "number"
    },
    "stroke": {
      "default": "rgba(98, 197, 255, 1)",
      "type": "string"
    },
    "cornerRadius": {
      "default": 0,
      "type": "number"
    }
  },
  "required": [
    "id",
    "type"
  ]
}
```

## Related Definitions [#related-definitions]

* [Animation](./animation)


---

# FontStyleVariant
URL: https://polotno.com/docs/schema/font-style-variant



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property     | Type     | Description                               |
| ------------ | -------- | ----------------------------------------- |
| `src`        | `string` | Font source, typically in CSS url() form. |
| `fontStyle`  | `string` | *No description provided*                 |
| `fontWeight` | `string` | *No description provided*                 |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "src": {
      "type": "string",
      "description": "Font source, typically in CSS url() form."
    },
    "fontStyle": {
      "type": "string"
    },
    "fontWeight": {
      "type": "string"
    }
  },
  "required": [
    "src"
  ]
}
```

## Related Definitions [#related-definitions]

*No related definitions found.*


---

# Font
URL: https://polotno.com/docs/schema/font



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property     | Type                                               | Description                                           |
| ------------ | -------------------------------------------------- | ----------------------------------------------------- |
| `fontFamily` | `string`                                           | Font family name.                                     |
| `url`        | `string`                                           | URL to load the font from (single-variant fonts).     |
| `styles`     | Array\<[`FontStyleVariant`](./font-style-variant)> | Per-weight/style variants for multi-variant families. |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "fontFamily": {
      "type": "string",
      "description": "Font family name."
    },
    "url": {
      "default": "",
      "description": "URL to load the font from (single-variant fonts).",
      "type": "string"
    },
    "styles": {
      "description": "Per-weight/style variants for multi-variant families.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "src": {
            "type": "string",
            "description": "Font source, typically in CSS url() form."
          },
          "fontStyle": {
            "type": "string"
          },
          "fontWeight": {
            "type": "string"
          }
        },
        "required": [
          "src"
        ]
      }
    }
  },
  "required": [
    "fontFamily"
  ]
}
```

## Related Definitions [#related-definitions]

* [FontStyleVariant](./font-style-variant)


---

# GifElement
URL: https://polotno.com/docs/schema/gif-element



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property            | Type                               | Description                                 |
| ------------------- | ---------------------------------- | ------------------------------------------- |
| `id`                | `string`                           | Unique identifier for the element.          |
| `type`              | `"gif"`                            | *No description provided*                   |
| `name`              | `string`                           | Display name for the element.               |
| `custom`            | `unknown`                          | Custom data attached to the element.        |
| `x`                 | `number`                           | X position in pixels.                       |
| `y`                 | `number`                           | Y position in pixels.                       |
| `width`             | `number`                           | Width in pixels.                            |
| `height`            | `number`                           | Height in pixels.                           |
| `rotation`          | `number`                           | Rotation angle in degrees.                  |
| `opacity`           | `number`                           | Opacity level (0-1).                        |
| `animations`        | Array\<[`Animation`](./animation)> | Animation configurations.                   |
| `blurEnabled`       | `boolean`                          | Whether blur effect is enabled.             |
| `blurRadius`        | `number`                           | Blur radius in pixels.                      |
| `brightnessEnabled` | `boolean`                          | Whether brightness effect is enabled.       |
| `brightness`        | `number`                           | Brightness level (-1 to 1).                 |
| `sepiaEnabled`      | `boolean`                          | Whether sepia effect is enabled.            |
| `grayscaleEnabled`  | `boolean`                          | Whether grayscale effect is enabled.        |
| `filters`           | `object`                           | Applied image filters keyed by filter name. |
| `shadowEnabled`     | `boolean`                          | Whether shadow is enabled.                  |
| `shadowBlur`        | `number`                           | Shadow blur radius in pixels.               |
| `shadowOffsetX`     | `number`                           | Shadow horizontal offset in pixels.         |
| `shadowOffsetY`     | `number`                           | Shadow vertical offset in pixels.           |
| `shadowColor`       | `string`                           | Shadow color.                               |
| `shadowOpacity`     | `number`                           | Shadow opacity (0-1).                       |
| `visible`           | `boolean`                          | Whether the element is visible.             |
| `draggable`         | `boolean`                          | Whether the element can be dragged.         |
| `resizable`         | `boolean`                          | Whether the element can be resized.         |
| `selectable`        | `boolean`                          | Whether the element can be selected.        |
| `removable`         | `boolean`                          | Whether the element can be removed.         |
| `contentEditable`   | `boolean`                          | Whether the element content can be edited.  |
| `styleEditable`     | `boolean`                          | Whether the element style can be edited.    |
| `alwaysOnTop`       | `boolean`                          | Whether the element stays on top of others. |
| `showInExport`      | `boolean`                          | Whether the element appears in exports.     |
| `src`               | `string`                           | URL or data URI of the image file.          |
| `cropX`             | `number`                           | Crop X offset as a fraction (0-1).          |
| `cropY`             | `number`                           | Crop Y offset as a fraction (0-1).          |
| `cropWidth`         | `number`                           | Crop width as a fraction (0-1).             |
| `cropHeight`        | `number`                           | Crop height as a fraction (0-1).            |
| `cornerRadius`      | `number`                           | Corner radius in pixels.                    |
| `flipX`             | `boolean`                          | Whether the image is flipped horizontally.  |
| `flipY`             | `boolean`                          | Whether the image is flipped vertically.    |
| `clipSrc`           | `string`                           | URL or data URI for a clipping mask.        |
| `borderColor`       | `string`                           | Border color.                               |
| `borderSize`        | `number`                           | Border width in pixels.                     |
| `keepRatio`         | `boolean`                          | *No description provided*                   |
| `stretchEnabled`    | `boolean`                          | Whether stretch mode is enabled.            |
| `duration`          | `number`                           | GIF duration in milliseconds.               |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the element."
    },
    "type": {
      "type": "string",
      "const": "gif"
    },
    "name": {
      "default": "",
      "description": "Display name for the element.",
      "type": "string"
    },
    "custom": {
      "description": "Custom data attached to the element."
    },
    "x": {
      "default": 0,
      "description": "X position in pixels.",
      "type": "number"
    },
    "y": {
      "default": 0,
      "description": "Y position in pixels.",
      "type": "number"
    },
    "width": {
      "default": 100,
      "description": "Width in pixels.",
      "type": "number"
    },
    "height": {
      "default": 100,
      "description": "Height in pixels.",
      "type": "number"
    },
    "rotation": {
      "default": 0,
      "description": "Rotation angle in degrees.",
      "type": "number"
    },
    "opacity": {
      "default": 1,
      "description": "Opacity level (0-1).",
      "type": "number"
    },
    "animations": {
      "default": [],
      "description": "Animation configurations.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "delay": {
            "default": 0,
            "description": "Delay before the animation starts, in milliseconds.",
            "type": "number"
          },
          "duration": {
            "default": 500,
            "description": "Animation duration in milliseconds.",
            "type": "number"
          },
          "enabled": {
            "default": true,
            "description": "Whether the animation is enabled.",
            "type": "boolean"
          },
          "type": {
            "type": "string",
            "enum": [
              "enter",
              "exit",
              "loop"
            ],
            "description": "Animation phase."
          },
          "name": {
            "default": "none",
            "description": "Animation name identifier.",
            "type": "string"
          },
          "data": {
            "default": {},
            "description": "Animation-specific data."
          }
        },
        "required": [
          "type"
        ]
      }
    },
    "blurEnabled": {
      "default": false,
      "description": "Whether blur effect is enabled.",
      "type": "boolean"
    },
    "blurRadius": {
      "default": 10,
      "description": "Blur radius in pixels.",
      "type": "number"
    },
    "brightnessEnabled": {
      "default": false,
      "description": "Whether brightness effect is enabled.",
      "type": "boolean"
    },
    "brightness": {
      "default": 0,
      "description": "Brightness level (-1 to 1).",
      "type": "number"
    },
    "sepiaEnabled": {
      "default": false,
      "description": "Whether sepia effect is enabled.",
      "type": "boolean"
    },
    "grayscaleEnabled": {
      "default": false,
      "description": "Whether grayscale effect is enabled.",
      "type": "boolean"
    },
    "filters": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "intensity": {
            "default": 1,
            "description": "Filter intensity (-1 to 1).",
            "type": "number"
          }
        }
      },
      "description": "Applied image filters keyed by filter name."
    },
    "shadowEnabled": {
      "default": false,
      "description": "Whether shadow is enabled.",
      "type": "boolean"
    },
    "shadowBlur": {
      "default": 5,
      "description": "Shadow blur radius in pixels.",
      "type": "number"
    },
    "shadowOffsetX": {
      "default": 0,
      "description": "Shadow horizontal offset in pixels.",
      "type": "number"
    },
    "shadowOffsetY": {
      "default": 0,
      "description": "Shadow vertical offset in pixels.",
      "type": "number"
    },
    "shadowColor": {
      "default": "black",
      "description": "Shadow color.",
      "type": "string"
    },
    "shadowOpacity": {
      "default": 1,
      "description": "Shadow opacity (0-1).",
      "type": "number"
    },
    "visible": {
      "default": true,
      "description": "Whether the element is visible.",
      "type": "boolean"
    },
    "draggable": {
      "default": true,
      "description": "Whether the element can be dragged.",
      "type": "boolean"
    },
    "resizable": {
      "default": true,
      "description": "Whether the element can be resized.",
      "type": "boolean"
    },
    "selectable": {
      "default": true,
      "description": "Whether the element can be selected.",
      "type": "boolean"
    },
    "removable": {
      "default": true,
      "description": "Whether the element can be removed.",
      "type": "boolean"
    },
    "contentEditable": {
      "default": true,
      "description": "Whether the element content can be edited.",
      "type": "boolean"
    },
    "styleEditable": {
      "default": true,
      "description": "Whether the element style can be edited.",
      "type": "boolean"
    },
    "alwaysOnTop": {
      "default": false,
      "description": "Whether the element stays on top of others.",
      "type": "boolean"
    },
    "showInExport": {
      "default": true,
      "description": "Whether the element appears in exports.",
      "type": "boolean"
    },
    "src": {
      "default": "",
      "description": "URL or data URI of the image file.",
      "type": "string"
    },
    "cropX": {
      "default": 0,
      "description": "Crop X offset as a fraction (0-1).",
      "type": "number"
    },
    "cropY": {
      "default": 0,
      "description": "Crop Y offset as a fraction (0-1).",
      "type": "number"
    },
    "cropWidth": {
      "default": 1,
      "description": "Crop width as a fraction (0-1).",
      "type": "number"
    },
    "cropHeight": {
      "default": 1,
      "description": "Crop height as a fraction (0-1).",
      "type": "number"
    },
    "cornerRadius": {
      "default": 0,
      "description": "Corner radius in pixels.",
      "type": "number"
    },
    "flipX": {
      "default": false,
      "description": "Whether the image is flipped horizontally.",
      "type": "boolean"
    },
    "flipY": {
      "default": false,
      "description": "Whether the image is flipped vertically.",
      "type": "boolean"
    },
    "clipSrc": {
      "default": "",
      "description": "URL or data URI for a clipping mask.",
      "type": "string"
    },
    "borderColor": {
      "default": "black",
      "description": "Border color.",
      "type": "string"
    },
    "borderSize": {
      "default": 0,
      "description": "Border width in pixels.",
      "type": "number"
    },
    "keepRatio": {
      "default": true,
      "type": "boolean"
    },
    "stretchEnabled": {
      "default": false,
      "description": "Whether stretch mode is enabled.",
      "type": "boolean"
    },
    "duration": {
      "default": 0,
      "description": "GIF duration in milliseconds.",
      "type": "number"
    }
  },
  "required": [
    "id",
    "type"
  ]
}
```

## Related Definitions [#related-definitions]

* [Animation](./animation)


---

# GroupElement
URL: https://polotno.com/docs/schema/group-element



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property       | Type                               | Description                   |
| -------------- | ---------------------------------- | ----------------------------- |
| `id`           | `string`                           | *No description provided*     |
| `type`         | `"group"`                          | *No description provided*     |
| `name`         | `string`                           | *No description provided*     |
| `custom`       | `unknown`                          | *No description provided*     |
| `opacity`      | `number`                           | *No description provided*     |
| `visible`      | `boolean`                          | *No description provided*     |
| `selectable`   | `boolean`                          | *No description provided*     |
| `removable`    | `boolean`                          | *No description provided*     |
| `alwaysOnTop`  | `boolean`                          | *No description provided*     |
| `showInExport` | `boolean`                          | *No description provided*     |
| `animations`   | Array\<[`Animation`](./animation)> | *No description provided*     |
| `children`     | Array\<[`Element`](./element)>     | Child elements in this group. |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "const": "group"
    },
    "name": {
      "default": "",
      "type": "string"
    },
    "custom": {},
    "opacity": {
      "default": 1,
      "type": "number"
    },
    "visible": {
      "default": true,
      "type": "boolean"
    },
    "selectable": {
      "default": true,
      "type": "boolean"
    },
    "removable": {
      "default": true,
      "type": "boolean"
    },
    "alwaysOnTop": {
      "default": false,
      "type": "boolean"
    },
    "showInExport": {
      "default": true,
      "type": "boolean"
    },
    "animations": {
      "default": [],
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "delay": {
            "default": 0,
            "description": "Delay before the animation starts, in milliseconds.",
            "type": "number"
          },
          "duration": {
            "default": 500,
            "description": "Animation duration in milliseconds.",
            "type": "number"
          },
          "enabled": {
            "default": true,
            "description": "Whether the animation is enabled.",
            "type": "boolean"
          },
          "type": {
            "type": "string",
            "enum": [
              "enter",
              "exit",
              "loop"
            ],
            "description": "Animation phase."
          },
          "name": {
            "default": "none",
            "description": "Animation name identifier.",
            "type": "string"
          },
          "data": {
            "default": {},
            "description": "Animation-specific data."
          }
        },
        "required": [
          "type"
        ]
      }
    },
    "children": {
      "default": [],
      "description": "Child elements in this group.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/__schema0"
      }
    }
  },
  "required": [
    "id",
    "type"
  ]
}
```

## Related Definitions [#related-definitions]

* [Animation](./animation)
* [Element](./element)


---

# ImageElement
URL: https://polotno.com/docs/schema/image-element



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property            | Type                               | Description                                     |
| ------------------- | ---------------------------------- | ----------------------------------------------- |
| `id`                | `string`                           | Unique identifier for the element.              |
| `type`              | `"image"`                          | *No description provided*                       |
| `name`              | `string`                           | Display name for the element.                   |
| `custom`            | `unknown`                          | Custom data attached to the element.            |
| `x`                 | `number`                           | X position in pixels.                           |
| `y`                 | `number`                           | Y position in pixels.                           |
| `width`             | `number`                           | Width in pixels.                                |
| `height`            | `number`                           | Height in pixels.                               |
| `rotation`          | `number`                           | Rotation angle in degrees.                      |
| `opacity`           | `number`                           | Opacity level (0-1).                            |
| `animations`        | Array\<[`Animation`](./animation)> | Animation configurations.                       |
| `blurEnabled`       | `boolean`                          | Whether blur effect is enabled.                 |
| `blurRadius`        | `number`                           | Blur radius in pixels.                          |
| `brightnessEnabled` | `boolean`                          | Whether brightness effect is enabled.           |
| `brightness`        | `number`                           | Brightness level (-1 to 1).                     |
| `sepiaEnabled`      | `boolean`                          | Whether sepia effect is enabled.                |
| `grayscaleEnabled`  | `boolean`                          | Whether grayscale effect is enabled.            |
| `filters`           | `object`                           | Applied image filters keyed by filter name.     |
| `shadowEnabled`     | `boolean`                          | Whether shadow is enabled.                      |
| `shadowBlur`        | `number`                           | Shadow blur radius in pixels.                   |
| `shadowOffsetX`     | `number`                           | Shadow horizontal offset in pixels.             |
| `shadowOffsetY`     | `number`                           | Shadow vertical offset in pixels.               |
| `shadowColor`       | `string`                           | Shadow color.                                   |
| `shadowOpacity`     | `number`                           | Shadow opacity (0-1).                           |
| `visible`           | `boolean`                          | Whether the element is visible.                 |
| `draggable`         | `boolean`                          | Whether the element can be dragged.             |
| `resizable`         | `boolean`                          | Whether the element can be resized.             |
| `selectable`        | `boolean`                          | Whether the element can be selected.            |
| `removable`         | `boolean`                          | Whether the element can be removed.             |
| `contentEditable`   | `boolean`                          | Whether the element content can be edited.      |
| `styleEditable`     | `boolean`                          | Whether the element style can be edited.        |
| `alwaysOnTop`       | `boolean`                          | Whether the element stays on top of others.     |
| `showInExport`      | `boolean`                          | Whether the element appears in exports.         |
| `src`               | `string`                           | URL or data URI of the image file.              |
| `cropX`             | `number`                           | Crop X offset as a fraction (0-1).              |
| `cropY`             | `number`                           | Crop Y offset as a fraction (0-1).              |
| `cropWidth`         | `number`                           | Crop width as a fraction (0-1).                 |
| `cropHeight`        | `number`                           | Crop height as a fraction (0-1).                |
| `cornerRadius`      | `number`                           | Corner radius in pixels.                        |
| `flipX`             | `boolean`                          | Whether the image is flipped horizontally.      |
| `flipY`             | `boolean`                          | Whether the image is flipped vertically.        |
| `clipSrc`           | `string`                           | URL or data URI for a clipping mask.            |
| `borderColor`       | `string`                           | Border color.                                   |
| `borderSize`        | `number`                           | Border width in pixels.                         |
| `keepRatio`         | `boolean`                          | Whether to maintain aspect ratio when resizing. |
| `stretchEnabled`    | `boolean`                          | Whether stretch mode is enabled.                |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the element."
    },
    "type": {
      "type": "string",
      "const": "image"
    },
    "name": {
      "default": "",
      "description": "Display name for the element.",
      "type": "string"
    },
    "custom": {
      "description": "Custom data attached to the element."
    },
    "x": {
      "default": 0,
      "description": "X position in pixels.",
      "type": "number"
    },
    "y": {
      "default": 0,
      "description": "Y position in pixels.",
      "type": "number"
    },
    "width": {
      "default": 100,
      "description": "Width in pixels.",
      "type": "number"
    },
    "height": {
      "default": 100,
      "description": "Height in pixels.",
      "type": "number"
    },
    "rotation": {
      "default": 0,
      "description": "Rotation angle in degrees.",
      "type": "number"
    },
    "opacity": {
      "default": 1,
      "description": "Opacity level (0-1).",
      "type": "number"
    },
    "animations": {
      "default": [],
      "description": "Animation configurations.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "delay": {
            "default": 0,
            "description": "Delay before the animation starts, in milliseconds.",
            "type": "number"
          },
          "duration": {
            "default": 500,
            "description": "Animation duration in milliseconds.",
            "type": "number"
          },
          "enabled": {
            "default": true,
            "description": "Whether the animation is enabled.",
            "type": "boolean"
          },
          "type": {
            "type": "string",
            "enum": [
              "enter",
              "exit",
              "loop"
            ],
            "description": "Animation phase."
          },
          "name": {
            "default": "none",
            "description": "Animation name identifier.",
            "type": "string"
          },
          "data": {
            "default": {},
            "description": "Animation-specific data."
          }
        },
        "required": [
          "type"
        ]
      }
    },
    "blurEnabled": {
      "default": false,
      "description": "Whether blur effect is enabled.",
      "type": "boolean"
    },
    "blurRadius": {
      "default": 10,
      "description": "Blur radius in pixels.",
      "type": "number"
    },
    "brightnessEnabled": {
      "default": false,
      "description": "Whether brightness effect is enabled.",
      "type": "boolean"
    },
    "brightness": {
      "default": 0,
      "description": "Brightness level (-1 to 1).",
      "type": "number"
    },
    "sepiaEnabled": {
      "default": false,
      "description": "Whether sepia effect is enabled.",
      "type": "boolean"
    },
    "grayscaleEnabled": {
      "default": false,
      "description": "Whether grayscale effect is enabled.",
      "type": "boolean"
    },
    "filters": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "intensity": {
            "default": 1,
            "description": "Filter intensity (-1 to 1).",
            "type": "number"
          }
        }
      },
      "description": "Applied image filters keyed by filter name."
    },
    "shadowEnabled": {
      "default": false,
      "description": "Whether shadow is enabled.",
      "type": "boolean"
    },
    "shadowBlur": {
      "default": 5,
      "description": "Shadow blur radius in pixels.",
      "type": "number"
    },
    "shadowOffsetX": {
      "default": 0,
      "description": "Shadow horizontal offset in pixels.",
      "type": "number"
    },
    "shadowOffsetY": {
      "default": 0,
      "description": "Shadow vertical offset in pixels.",
      "type": "number"
    },
    "shadowColor": {
      "default": "black",
      "description": "Shadow color.",
      "type": "string"
    },
    "shadowOpacity": {
      "default": 1,
      "description": "Shadow opacity (0-1).",
      "type": "number"
    },
    "visible": {
      "default": true,
      "description": "Whether the element is visible.",
      "type": "boolean"
    },
    "draggable": {
      "default": true,
      "description": "Whether the element can be dragged.",
      "type": "boolean"
    },
    "resizable": {
      "default": true,
      "description": "Whether the element can be resized.",
      "type": "boolean"
    },
    "selectable": {
      "default": true,
      "description": "Whether the element can be selected.",
      "type": "boolean"
    },
    "removable": {
      "default": true,
      "description": "Whether the element can be removed.",
      "type": "boolean"
    },
    "contentEditable": {
      "default": true,
      "description": "Whether the element content can be edited.",
      "type": "boolean"
    },
    "styleEditable": {
      "default": true,
      "description": "Whether the element style can be edited.",
      "type": "boolean"
    },
    "alwaysOnTop": {
      "default": false,
      "description": "Whether the element stays on top of others.",
      "type": "boolean"
    },
    "showInExport": {
      "default": true,
      "description": "Whether the element appears in exports.",
      "type": "boolean"
    },
    "src": {
      "default": "",
      "description": "URL or data URI of the image file.",
      "type": "string"
    },
    "cropX": {
      "default": 0,
      "description": "Crop X offset as a fraction (0-1).",
      "type": "number"
    },
    "cropY": {
      "default": 0,
      "description": "Crop Y offset as a fraction (0-1).",
      "type": "number"
    },
    "cropWidth": {
      "default": 1,
      "description": "Crop width as a fraction (0-1).",
      "type": "number"
    },
    "cropHeight": {
      "default": 1,
      "description": "Crop height as a fraction (0-1).",
      "type": "number"
    },
    "cornerRadius": {
      "default": 0,
      "description": "Corner radius in pixels.",
      "type": "number"
    },
    "flipX": {
      "default": false,
      "description": "Whether the image is flipped horizontally.",
      "type": "boolean"
    },
    "flipY": {
      "default": false,
      "description": "Whether the image is flipped vertically.",
      "type": "boolean"
    },
    "clipSrc": {
      "default": "",
      "description": "URL or data URI for a clipping mask.",
      "type": "string"
    },
    "borderColor": {
      "default": "black",
      "description": "Border color.",
      "type": "string"
    },
    "borderSize": {
      "default": 0,
      "description": "Border width in pixels.",
      "type": "number"
    },
    "keepRatio": {
      "default": false,
      "description": "Whether to maintain aspect ratio when resizing.",
      "type": "boolean"
    },
    "stretchEnabled": {
      "default": false,
      "description": "Whether stretch mode is enabled.",
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "type"
  ]
}
```

## Related Definitions [#related-definitions]

* [Animation](./animation)


---

# Design Format
URL: https://polotno.com/docs/schema





The **Design Format** is the JSON shape every Polotno design uses — the same object `store.toJSON()` produces and `store.loadJSON()` accepts. It's a flat, readable document: top-level `width` / `height` / `dpi`, a `fonts` array, and a `pages` array whose `children` are typed elements (text, image, svg, line, figure, gif, video, table, group).

You can work with this format **without running the editor**. The [`@polotno/schema`](https://www.npmjs.com/package/@polotno/schema) package gives you TypeScript types, default values, validation, and a language-neutral JSON Schema — everything you need to generate, validate, or transform designs on a server, in an edge function, or inside an LLM pipeline.

```bash
npm install @polotno/schema
```

## What it's for [#what-its-for]

* **Validate** a design before saving it, or when accepting it over the wire.
* **Normalize** partial or hand-authored JSON into a complete, canonical document (defaults filled in).
* **Constrain LLM output** — feed the JSON Schema to a model as a structured-output schema, then validate what comes back.

## Validate [#validate]

```ts
import { validateDesign } from '@polotno/schema';

// json from store.toJSON(), a converter, or an LLM
const result = validateDesign(json, { mode: 'canonical' });
if (!result.valid) {
  console.error(result.errors); // [{ path, message }, …]
}
```

Use `mode: 'partial'` to allow missing defaults, or `mode: 'canonical'` to reject unknown keys. `assertValidDesign(json)` throws instead of returning a result. The exported `designSchemaLenient` / `designSchemaCanonical` implement the [Standard Schema](https://standardschema.dev) interface (zod, Valibot, Effect Schema, …).

## Normalize (fill defaults) [#normalize-fill-defaults]

```ts
import { normalizeDesign } from '@polotno/schema';

const complete = normalizeDesign(partial); // fills defaults, strips unknown keys
store.loadJSON(complete);
```

Normalize is idempotent for current-format input. It does **not** migrate old `schemaVersion` documents, and it leaves render-derived values (such as text auto-height) for the editor to compute.

## Types [#types]

```ts
import type { Design } from '@polotno/schema';

const design: Design = store.toJSON();
```

Also exported: `Page`, `Element`, `TextElement`, and every other type in the format.

## JSON Schema & LLMs [#json-schema--llms]

A language-neutral JSON Schema (draft 2020-12) ships with the package — validate from any language, or hand it to a model as a structured-output schema and validate what comes back before rendering:

```ts
import schema from '@polotno/schema/design.schema.json' with { type: 'json' };
import { validateDesign } from '@polotno/schema';

// `schema` as your LLM client's structured-output / response schema
const design = await model.generate({ prompt, jsonSchema: schema });

if (validateDesign(design, { mode: 'partial' }).valid) {
  store.loadJSON(design);
}
```

## Field reference [#field-reference]

Every type in the format has a generated reference page with all properties, types, and defaults:

* [Design](/docs/schema/store) — the root document
* [Page](/docs/schema/page) and its [Element](/docs/schema/element) children: [Text](/docs/schema/text-element), [Image](/docs/schema/image-element), [SVG](/docs/schema/svg-element), [Line](/docs/schema/line-element), [Figure](/docs/schema/figure-element), [Gif](/docs/schema/gif-element), [Video](/docs/schema/video-element), [Table](/docs/schema/table-element), [Group](/docs/schema/group-element)
* [Font](/docs/schema/font) and [Audio](/docs/schema/audio)

Browse the full list in the sidebar. For the complete package API, see the [`@polotno/schema` README](https://www.npmjs.com/package/@polotno/schema) on npm.

<Callout type="info">
  `@polotno/schema` is part of the Polotno SDK. Production use requires a valid
  Polotno [subscription](https://polotno.com/legal/license). The format is at
  `schemaVersion` 4 and still pre-1.0 — expect additive changes.
</Callout>


---

# LineElement
URL: https://polotno.com/docs/schema/line-element



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property            | Type                               | Description                                          |
| ------------------- | ---------------------------------- | ---------------------------------------------------- |
| `id`                | `string`                           | Unique identifier for the element.                   |
| `type`              | `"line"`                           | *No description provided*                            |
| `name`              | `string`                           | Display name for the element.                        |
| `custom`            | `unknown`                          | Custom data attached to the element.                 |
| `x`                 | `number`                           | X position in pixels.                                |
| `y`                 | `number`                           | Y position in pixels.                                |
| `width`             | `number`                           | *No description provided*                            |
| `height`            | `number`                           | *No description provided*                            |
| `rotation`          | `number`                           | Rotation angle in degrees.                           |
| `opacity`           | `number`                           | Opacity level (0-1).                                 |
| `animations`        | Array\<[`Animation`](./animation)> | Animation configurations.                            |
| `blurEnabled`       | `boolean`                          | Whether blur effect is enabled.                      |
| `blurRadius`        | `number`                           | Blur radius in pixels.                               |
| `brightnessEnabled` | `boolean`                          | Whether brightness effect is enabled.                |
| `brightness`        | `number`                           | Brightness level (-1 to 1).                          |
| `sepiaEnabled`      | `boolean`                          | Whether sepia effect is enabled.                     |
| `grayscaleEnabled`  | `boolean`                          | Whether grayscale effect is enabled.                 |
| `filters`           | `object`                           | Applied image filters keyed by filter name.          |
| `shadowEnabled`     | `boolean`                          | Whether shadow is enabled.                           |
| `shadowBlur`        | `number`                           | Shadow blur radius in pixels.                        |
| `shadowOffsetX`     | `number`                           | Shadow horizontal offset in pixels.                  |
| `shadowOffsetY`     | `number`                           | Shadow vertical offset in pixels.                    |
| `shadowColor`       | `string`                           | Shadow color.                                        |
| `shadowOpacity`     | `number`                           | Shadow opacity (0-1).                                |
| `visible`           | `boolean`                          | Whether the element is visible.                      |
| `draggable`         | `boolean`                          | Whether the element can be dragged.                  |
| `resizable`         | `boolean`                          | Whether the element can be resized.                  |
| `selectable`        | `boolean`                          | Whether the element can be selected.                 |
| `removable`         | `boolean`                          | Whether the element can be removed.                  |
| `contentEditable`   | `boolean`                          | Whether the element content can be edited.           |
| `styleEditable`     | `boolean`                          | Whether the element style can be edited.             |
| `alwaysOnTop`       | `boolean`                          | Whether the element stays on top of others.          |
| `showInExport`      | `boolean`                          | Whether the element appears in exports.              |
| `color`             | `string`                           | Line color.                                          |
| `dash`              | Array\<`number`>                   | Dash pattern array.                                  |
| `startHead`         | `string`                           | Start arrow head: empty, arrow, circle, square, bar. |
| `endHead`           | `string`                           | End arrow head: empty, arrow, circle, square, bar.   |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the element."
    },
    "type": {
      "type": "string",
      "const": "line"
    },
    "name": {
      "default": "",
      "description": "Display name for the element.",
      "type": "string"
    },
    "custom": {
      "description": "Custom data attached to the element."
    },
    "x": {
      "default": 0,
      "description": "X position in pixels.",
      "type": "number"
    },
    "y": {
      "default": 0,
      "description": "Y position in pixels.",
      "type": "number"
    },
    "width": {
      "default": 400,
      "type": "number"
    },
    "height": {
      "default": 10,
      "type": "number"
    },
    "rotation": {
      "default": 0,
      "description": "Rotation angle in degrees.",
      "type": "number"
    },
    "opacity": {
      "default": 1,
      "description": "Opacity level (0-1).",
      "type": "number"
    },
    "animations": {
      "default": [],
      "description": "Animation configurations.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "delay": {
            "default": 0,
            "description": "Delay before the animation starts, in milliseconds.",
            "type": "number"
          },
          "duration": {
            "default": 500,
            "description": "Animation duration in milliseconds.",
            "type": "number"
          },
          "enabled": {
            "default": true,
            "description": "Whether the animation is enabled.",
            "type": "boolean"
          },
          "type": {
            "type": "string",
            "enum": [
              "enter",
              "exit",
              "loop"
            ],
            "description": "Animation phase."
          },
          "name": {
            "default": "none",
            "description": "Animation name identifier.",
            "type": "string"
          },
          "data": {
            "default": {},
            "description": "Animation-specific data."
          }
        },
        "required": [
          "type"
        ]
      }
    },
    "blurEnabled": {
      "default": false,
      "description": "Whether blur effect is enabled.",
      "type": "boolean"
    },
    "blurRadius": {
      "default": 10,
      "description": "Blur radius in pixels.",
      "type": "number"
    },
    "brightnessEnabled": {
      "default": false,
      "description": "Whether brightness effect is enabled.",
      "type": "boolean"
    },
    "brightness": {
      "default": 0,
      "description": "Brightness level (-1 to 1).",
      "type": "number"
    },
    "sepiaEnabled": {
      "default": false,
      "description": "Whether sepia effect is enabled.",
      "type": "boolean"
    },
    "grayscaleEnabled": {
      "default": false,
      "description": "Whether grayscale effect is enabled.",
      "type": "boolean"
    },
    "filters": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "intensity": {
            "default": 1,
            "description": "Filter intensity (-1 to 1).",
            "type": "number"
          }
        }
      },
      "description": "Applied image filters keyed by filter name."
    },
    "shadowEnabled": {
      "default": false,
      "description": "Whether shadow is enabled.",
      "type": "boolean"
    },
    "shadowBlur": {
      "default": 5,
      "description": "Shadow blur radius in pixels.",
      "type": "number"
    },
    "shadowOffsetX": {
      "default": 0,
      "description": "Shadow horizontal offset in pixels.",
      "type": "number"
    },
    "shadowOffsetY": {
      "default": 0,
      "description": "Shadow vertical offset in pixels.",
      "type": "number"
    },
    "shadowColor": {
      "default": "black",
      "description": "Shadow color.",
      "type": "string"
    },
    "shadowOpacity": {
      "default": 1,
      "description": "Shadow opacity (0-1).",
      "type": "number"
    },
    "visible": {
      "default": true,
      "description": "Whether the element is visible.",
      "type": "boolean"
    },
    "draggable": {
      "default": true,
      "description": "Whether the element can be dragged.",
      "type": "boolean"
    },
    "resizable": {
      "default": true,
      "description": "Whether the element can be resized.",
      "type": "boolean"
    },
    "selectable": {
      "default": true,
      "description": "Whether the element can be selected.",
      "type": "boolean"
    },
    "removable": {
      "default": true,
      "description": "Whether the element can be removed.",
      "type": "boolean"
    },
    "contentEditable": {
      "default": true,
      "description": "Whether the element content can be edited.",
      "type": "boolean"
    },
    "styleEditable": {
      "default": true,
      "description": "Whether the element style can be edited.",
      "type": "boolean"
    },
    "alwaysOnTop": {
      "default": false,
      "description": "Whether the element stays on top of others.",
      "type": "boolean"
    },
    "showInExport": {
      "default": true,
      "description": "Whether the element appears in exports.",
      "type": "boolean"
    },
    "color": {
      "default": "black",
      "description": "Line color.",
      "type": "string"
    },
    "dash": {
      "default": [],
      "description": "Dash pattern array.",
      "type": "array",
      "items": {
        "type": "number"
      }
    },
    "startHead": {
      "default": "",
      "description": "Start arrow head: empty, arrow, circle, square, bar.",
      "type": "string"
    },
    "endHead": {
      "default": "",
      "description": "End arrow head: empty, arrow, circle, square, bar.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type"
  ]
}
```

## Related Definitions [#related-definitions]

* [Animation](./animation)


---

# Page
URL: https://polotno.com/docs/schema/page



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property      | Type                           | Description                                                                    |
| ------------- | ------------------------------ | ------------------------------------------------------------------------------ |
| `id`          | `string`                       | Unique identifier for the page.                                                |
| `width`       | `number` \| `"auto"`           | Page width in pixels or 'auto'.                                                |
| `height`      | `number` \| `"auto"`           | Page height in pixels or 'auto'.                                               |
| `background`  | `string`                       | Background color or image.                                                     |
| `bleed`       | `number`                       | Bleed area in pixels for print (all sides; base value for per-side overrides). |
| `bleedTop`    | `number`                       | Per-side bleed override (top), in pixels. Inherits `bleed` when omitted.       |
| `bleedRight`  | `number`                       | Per-side bleed override (right), in pixels. Inherits `bleed` when omitted.     |
| `bleedBottom` | `number`                       | Per-side bleed override (bottom), in pixels. Inherits `bleed` when omitted.    |
| `bleedLeft`   | `number`                       | Per-side bleed override (left), in pixels. Inherits `bleed` when omitted.      |
| `custom`      | `unknown`                      | *No description provided*                                                      |
| `duration`    | `number`                       | Page duration in milliseconds.                                                 |
| `children`    | Array\<[`Element`](./element)> | Elements on this page.                                                         |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the page."
    },
    "width": {
      "default": "auto",
      "description": "Page width in pixels or 'auto'.",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "const": "auto"
        }
      ]
    },
    "height": {
      "default": "auto",
      "description": "Page height in pixels or 'auto'.",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "const": "auto"
        }
      ]
    },
    "background": {
      "default": "white",
      "description": "Background color or image.",
      "type": "string"
    },
    "bleed": {
      "default": 0,
      "description": "Bleed area in pixels for print (all sides; base value for per-side overrides).",
      "type": "number"
    },
    "bleedTop": {
      "description": "Per-side bleed override (top), in pixels. Inherits `bleed` when omitted.",
      "type": "number"
    },
    "bleedRight": {
      "description": "Per-side bleed override (right), in pixels. Inherits `bleed` when omitted.",
      "type": "number"
    },
    "bleedBottom": {
      "description": "Per-side bleed override (bottom), in pixels. Inherits `bleed` when omitted.",
      "type": "number"
    },
    "bleedLeft": {
      "description": "Per-side bleed override (left), in pixels. Inherits `bleed` when omitted.",
      "type": "number"
    },
    "custom": {},
    "duration": {
      "default": 5000,
      "description": "Page duration in milliseconds.",
      "type": "number"
    },
    "children": {
      "default": [],
      "description": "Elements on this page.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/__schema0"
      }
    }
  },
  "required": [
    "id"
  ]
}
```

## Related Definitions [#related-definitions]

* [Element](./element)


---

# Design
URL: https://polotno.com/docs/schema/store



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property        | Type                                           | Description                                   |
| --------------- | ---------------------------------------------- | --------------------------------------------- |
| `schemaVersion` | `number`                                       | Schema version for compatibility / migration. |
| `width`         | `number`                                       | Canvas width in pixels.                       |
| `height`        | `number`                                       | Canvas height in pixels.                      |
| `unit`          | `"px"` \| `"pt"` \| `"mm"` \| `"cm"` \| `"in"` | Unit type for print measurements.             |
| `dpi`           | `number`                                       | Dots per inch for print calculations.         |
| `custom`        | `unknown`                                      | Custom data attached to the design.           |
| `fonts`         | Array\<[`Font`](./font)>                       | Fonts used in the design.                     |
| `pages`         | Array\<[`Page`](./page)>                       | Pages in the design.                          |
| `audios`        | Array\<[`Audio`](./audio)>                     | Audio tracks in the design.                   |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "schemaVersion": {
      "default": 4,
      "description": "Schema version for compatibility / migration.",
      "type": "number"
    },
    "width": {
      "default": 1080,
      "description": "Canvas width in pixels.",
      "type": "number"
    },
    "height": {
      "default": 1080,
      "description": "Canvas height in pixels.",
      "type": "number"
    },
    "unit": {
      "default": "px",
      "description": "Unit type for print measurements.",
      "type": "string",
      "enum": [
        "px",
        "pt",
        "mm",
        "cm",
        "in"
      ]
    },
    "dpi": {
      "default": 72,
      "description": "Dots per inch for print calculations.",
      "type": "number"
    },
    "custom": {
      "description": "Custom data attached to the design."
    },
    "fonts": {
      "default": [],
      "description": "Fonts used in the design.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fontFamily": {
            "type": "string",
            "description": "Font family name."
          },
          "url": {
            "default": "",
            "description": "URL to load the font from (single-variant fonts).",
            "type": "string"
          },
          "styles": {
            "description": "Per-weight/style variants for multi-variant families.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "src": {
                  "type": "string",
                  "description": "Font source, typically in CSS url() form."
                },
                "fontStyle": {
                  "type": "string"
                },
                "fontWeight": {
                  "type": "string"
                }
              },
              "required": [
                "src"
              ]
            }
          }
        },
        "required": [
          "fontFamily"
        ]
      }
    },
    "pages": {
      "default": [],
      "description": "Pages in the design.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the page."
          },
          "width": {
            "default": "auto",
            "description": "Page width in pixels or 'auto'.",
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string",
                "const": "auto"
              }
            ]
          },
          "height": {
            "default": "auto",
            "description": "Page height in pixels or 'auto'.",
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string",
                "const": "auto"
              }
            ]
          },
          "background": {
            "default": "white",
            "description": "Background color or image.",
            "type": "string"
          },
          "bleed": {
            "default": 0,
            "description": "Bleed area in pixels for print (all sides; base value for per-side overrides).",
            "type": "number"
          },
          "bleedTop": {
            "description": "Per-side bleed override (top), in pixels. Inherits `bleed` when omitted.",
            "type": "number"
          },
          "bleedRight": {
            "description": "Per-side bleed override (right), in pixels. Inherits `bleed` when omitted.",
            "type": "number"
          },
          "bleedBottom": {
            "description": "Per-side bleed override (bottom), in pixels. Inherits `bleed` when omitted.",
            "type": "number"
          },
          "bleedLeft": {
            "description": "Per-side bleed override (left), in pixels. Inherits `bleed` when omitted.",
            "type": "number"
          },
          "custom": {},
          "duration": {
            "default": 5000,
            "description": "Page duration in milliseconds.",
            "type": "number"
          },
          "children": {
            "default": [],
            "description": "Elements on this page.",
            "type": "array",
            "items": {
              "$ref": "#/$defs/__schema0"
            }
          }
        },
        "required": [
          "id"
        ]
      }
    },
    "audios": {
      "default": [],
      "description": "Audio tracks in the design.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the audio track."
          },
          "src": {
            "default": "",
            "description": "URL or data URI of the audio file.",
            "type": "string"
          },
          "duration": {
            "default": 0,
            "description": "Duration in milliseconds.",
            "type": "number"
          },
          "startTime": {
            "default": 0,
            "description": "Start offset (0-1).",
            "type": "number"
          },
          "endTime": {
            "default": 1,
            "description": "End offset (0-1).",
            "type": "number"
          },
          "volume": {
            "default": 1,
            "description": "Volume level (0-1).",
            "type": "number"
          },
          "delay": {
            "default": 0,
            "description": "Delay before playing, in milliseconds.",
            "type": "number"
          },
          "speed": {
            "default": 1,
            "description": "Playback speed multiplier (1 = normal).",
            "type": "number"
          },
          "custom": {}
        },
        "required": [
          "id"
        ]
      }
    }
  }
}
```

## Related Definitions [#related-definitions]

* [Font](./font)
* [Page](./page)
* [Audio](./audio)
* [FontStyleVariant](./font-style-variant)
* [Element](./element)
* [Animation](./animation)
* [TableCell](./table-cell)
* [CellBorders](./cell-borders)
* [BorderSide](./border-side)


---

# SVGElement
URL: https://polotno.com/docs/schema/svg-element



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property            | Type                               | Description                                          |
| ------------------- | ---------------------------------- | ---------------------------------------------------- |
| `id`                | `string`                           | Unique identifier for the element.                   |
| `type`              | `"svg"`                            | *No description provided*                            |
| `name`              | `string`                           | Display name for the element.                        |
| `custom`            | `unknown`                          | Custom data attached to the element.                 |
| `x`                 | `number`                           | X position in pixels.                                |
| `y`                 | `number`                           | Y position in pixels.                                |
| `width`             | `number`                           | *No description provided*                            |
| `height`            | `number`                           | *No description provided*                            |
| `rotation`          | `number`                           | Rotation angle in degrees.                           |
| `opacity`           | `number`                           | Opacity level (0-1).                                 |
| `animations`        | Array\<[`Animation`](./animation)> | Animation configurations.                            |
| `blurEnabled`       | `boolean`                          | Whether blur effect is enabled.                      |
| `blurRadius`        | `number`                           | Blur radius in pixels.                               |
| `brightnessEnabled` | `boolean`                          | Whether brightness effect is enabled.                |
| `brightness`        | `number`                           | Brightness level (-1 to 1).                          |
| `sepiaEnabled`      | `boolean`                          | Whether sepia effect is enabled.                     |
| `grayscaleEnabled`  | `boolean`                          | Whether grayscale effect is enabled.                 |
| `filters`           | `object`                           | Applied image filters keyed by filter name.          |
| `shadowEnabled`     | `boolean`                          | Whether shadow is enabled.                           |
| `shadowBlur`        | `number`                           | Shadow blur radius in pixels.                        |
| `shadowOffsetX`     | `number`                           | Shadow horizontal offset in pixels.                  |
| `shadowOffsetY`     | `number`                           | Shadow vertical offset in pixels.                    |
| `shadowColor`       | `string`                           | Shadow color.                                        |
| `shadowOpacity`     | `number`                           | Shadow opacity (0-1).                                |
| `visible`           | `boolean`                          | Whether the element is visible.                      |
| `draggable`         | `boolean`                          | Whether the element can be dragged.                  |
| `resizable`         | `boolean`                          | Whether the element can be resized.                  |
| `selectable`        | `boolean`                          | Whether the element can be selected.                 |
| `removable`         | `boolean`                          | Whether the element can be removed.                  |
| `contentEditable`   | `boolean`                          | Whether the element content can be edited.           |
| `styleEditable`     | `boolean`                          | Whether the element style can be edited.             |
| `alwaysOnTop`       | `boolean`                          | Whether the element stays on top of others.          |
| `showInExport`      | `boolean`                          | Whether the element appears in exports.              |
| `src`               | `string`                           | URL or data URI of the SVG.                          |
| `maskSrc`           | `string`                           | URL or data URI for an SVG mask.                     |
| `cropX`             | `number`                           | *No description provided*                            |
| `cropY`             | `number`                           | *No description provided*                            |
| `cropWidth`         | `number`                           | *No description provided*                            |
| `cropHeight`        | `number`                           | *No description provided*                            |
| `keepRatio`         | `boolean`                          | *No description provided*                            |
| `stretchEnabled`    | `boolean`                          | *No description provided*                            |
| `flipX`             | `boolean`                          | *No description provided*                            |
| `flipY`             | `boolean`                          | *No description provided*                            |
| `borderColor`       | `string`                           | *No description provided*                            |
| `borderSize`        | `number`                           | *No description provided*                            |
| `cornerRadius`      | `number`                           | *No description provided*                            |
| `colorsReplace`     | `object`                           | Color replacement mappings (original → replacement). |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the element."
    },
    "type": {
      "type": "string",
      "const": "svg"
    },
    "name": {
      "default": "",
      "description": "Display name for the element.",
      "type": "string"
    },
    "custom": {
      "description": "Custom data attached to the element."
    },
    "x": {
      "default": 0,
      "description": "X position in pixels.",
      "type": "number"
    },
    "y": {
      "default": 0,
      "description": "Y position in pixels.",
      "type": "number"
    },
    "width": {
      "default": 100,
      "type": "number"
    },
    "height": {
      "default": 100,
      "type": "number"
    },
    "rotation": {
      "default": 0,
      "description": "Rotation angle in degrees.",
      "type": "number"
    },
    "opacity": {
      "default": 1,
      "description": "Opacity level (0-1).",
      "type": "number"
    },
    "animations": {
      "default": [],
      "description": "Animation configurations.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "delay": {
            "default": 0,
            "description": "Delay before the animation starts, in milliseconds.",
            "type": "number"
          },
          "duration": {
            "default": 500,
            "description": "Animation duration in milliseconds.",
            "type": "number"
          },
          "enabled": {
            "default": true,
            "description": "Whether the animation is enabled.",
            "type": "boolean"
          },
          "type": {
            "type": "string",
            "enum": [
              "enter",
              "exit",
              "loop"
            ],
            "description": "Animation phase."
          },
          "name": {
            "default": "none",
            "description": "Animation name identifier.",
            "type": "string"
          },
          "data": {
            "default": {},
            "description": "Animation-specific data."
          }
        },
        "required": [
          "type"
        ]
      }
    },
    "blurEnabled": {
      "default": false,
      "description": "Whether blur effect is enabled.",
      "type": "boolean"
    },
    "blurRadius": {
      "default": 10,
      "description": "Blur radius in pixels.",
      "type": "number"
    },
    "brightnessEnabled": {
      "default": false,
      "description": "Whether brightness effect is enabled.",
      "type": "boolean"
    },
    "brightness": {
      "default": 0,
      "description": "Brightness level (-1 to 1).",
      "type": "number"
    },
    "sepiaEnabled": {
      "default": false,
      "description": "Whether sepia effect is enabled.",
      "type": "boolean"
    },
    "grayscaleEnabled": {
      "default": false,
      "description": "Whether grayscale effect is enabled.",
      "type": "boolean"
    },
    "filters": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "intensity": {
            "default": 1,
            "description": "Filter intensity (-1 to 1).",
            "type": "number"
          }
        }
      },
      "description": "Applied image filters keyed by filter name."
    },
    "shadowEnabled": {
      "default": false,
      "description": "Whether shadow is enabled.",
      "type": "boolean"
    },
    "shadowBlur": {
      "default": 5,
      "description": "Shadow blur radius in pixels.",
      "type": "number"
    },
    "shadowOffsetX": {
      "default": 0,
      "description": "Shadow horizontal offset in pixels.",
      "type": "number"
    },
    "shadowOffsetY": {
      "default": 0,
      "description": "Shadow vertical offset in pixels.",
      "type": "number"
    },
    "shadowColor": {
      "default": "black",
      "description": "Shadow color.",
      "type": "string"
    },
    "shadowOpacity": {
      "default": 1,
      "description": "Shadow opacity (0-1).",
      "type": "number"
    },
    "visible": {
      "default": true,
      "description": "Whether the element is visible.",
      "type": "boolean"
    },
    "draggable": {
      "default": true,
      "description": "Whether the element can be dragged.",
      "type": "boolean"
    },
    "resizable": {
      "default": true,
      "description": "Whether the element can be resized.",
      "type": "boolean"
    },
    "selectable": {
      "default": true,
      "description": "Whether the element can be selected.",
      "type": "boolean"
    },
    "removable": {
      "default": true,
      "description": "Whether the element can be removed.",
      "type": "boolean"
    },
    "contentEditable": {
      "default": true,
      "description": "Whether the element content can be edited.",
      "type": "boolean"
    },
    "styleEditable": {
      "default": true,
      "description": "Whether the element style can be edited.",
      "type": "boolean"
    },
    "alwaysOnTop": {
      "default": false,
      "description": "Whether the element stays on top of others.",
      "type": "boolean"
    },
    "showInExport": {
      "default": true,
      "description": "Whether the element appears in exports.",
      "type": "boolean"
    },
    "src": {
      "default": "",
      "description": "URL or data URI of the SVG.",
      "type": "string"
    },
    "maskSrc": {
      "default": "",
      "description": "URL or data URI for an SVG mask.",
      "type": "string"
    },
    "cropX": {
      "default": 0,
      "type": "number"
    },
    "cropY": {
      "default": 0,
      "type": "number"
    },
    "cropWidth": {
      "default": 1,
      "type": "number"
    },
    "cropHeight": {
      "default": 1,
      "type": "number"
    },
    "keepRatio": {
      "default": true,
      "type": "boolean"
    },
    "stretchEnabled": {
      "default": true,
      "type": "boolean"
    },
    "flipX": {
      "default": false,
      "type": "boolean"
    },
    "flipY": {
      "default": false,
      "type": "boolean"
    },
    "borderColor": {
      "default": "black",
      "type": "string"
    },
    "borderSize": {
      "default": 0,
      "type": "number"
    },
    "cornerRadius": {
      "default": 0,
      "type": "number"
    },
    "colorsReplace": {
      "default": {},
      "description": "Color replacement mappings (original → replacement).",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "required": [
    "id",
    "type"
  ]
}
```

## Related Definitions [#related-definitions]

* [Animation](./animation)


---

# TableCell
URL: https://polotno.com/docs/schema/table-cell



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property         | Type                            | Description                                                                                    |
| ---------------- | ------------------------------- | ---------------------------------------------------------------------------------------------- |
| `id`             | `string`                        | Unique identifier for the cell.                                                                |
| `type`           | `"tablecell"`                   | Cell type identifier.                                                                          |
| `text`           | `string`                        | Visible text shown in the cell.                                                                |
| `opacity`        | `number`                        | Opacity level (0-1).                                                                           |
| `rowSpan`        | `number`                        | Number of rows this cell spans.                                                                |
| `colSpan`        | `number`                        | Number of columns this cell spans.                                                             |
| `mergedInto`     | `string`                        | Id of the cell this one is merged into, if any.                                                |
| `name`           | `string`                        | Display name for the cell.                                                                     |
| `custom`         | `unknown`                       | Custom data attached to the cell.                                                              |
| `borders`        | [`CellBorders`](./cell-borders) | Per-side border overrides for this cell.                                                       |
| `fontSize`       | `number`                        | Font size in pixels (inherits from the table when omitted).                                    |
| `fontFamily`     | `string`                        | Font family name (inherits from the table when omitted).                                       |
| `fontWeight`     | `string`                        | Font weight: 'normal', 'bold', or numeric string (inherits from the table when omitted).       |
| `fontStyle`      | `string`                        | Font style: 'normal' or 'italic' (inherits from the table when omitted).                       |
| `textDecoration` | `string`                        | Text decoration, e.g. underline, line-through (inherits from the table when omitted).          |
| `textTransform`  | `string`                        | Text transform: uppercase, lowercase, capitalize, none (inherits from the table when omitted). |
| `fill`           | `string`                        | Text color (inherits from the table when omitted).                                             |
| `align`          | `string`                        | Horizontal alignment: left, center, right, justify (inherits from the table when omitted).     |
| `verticalAlign`  | `string`                        | Vertical alignment: top, middle, bottom (inherits from the table when omitted).                |
| `lineHeight`     | `number` \| `string`            | Line height multiplier or 'auto' (inherits from the table when omitted).                       |
| `letterSpacing`  | `number`                        | Letter spacing as a fraction of font size (inherits from the table when omitted).              |
| `strokeWidth`    | `number`                        | Stroke width in pixels (inherits from the table when omitted).                                 |
| `stroke`         | `string`                        | Stroke color (inherits from the table when omitted).                                           |
| `cellBackground` | `string`                        | Cell background color (inherits from the table when omitted).                                  |
| `cellPadding`    | `number`                        | Cell padding in pixels (inherits from the table when omitted).                                 |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the cell."
    },
    "type": {
      "default": "tablecell",
      "description": "Cell type identifier.",
      "type": "string",
      "const": "tablecell"
    },
    "text": {
      "default": "",
      "description": "Visible text shown in the cell.",
      "type": "string"
    },
    "opacity": {
      "description": "Opacity level (0-1).",
      "type": "number"
    },
    "rowSpan": {
      "description": "Number of rows this cell spans.",
      "type": "number"
    },
    "colSpan": {
      "description": "Number of columns this cell spans.",
      "type": "number"
    },
    "mergedInto": {
      "description": "Id of the cell this one is merged into, if any.",
      "type": "string"
    },
    "name": {
      "description": "Display name for the cell.",
      "type": "string"
    },
    "custom": {
      "description": "Custom data attached to the cell."
    },
    "borders": {
      "description": "Per-side border overrides for this cell.",
      "type": "object",
      "properties": {
        "top": {
          "description": "Top border override for this cell.",
          "type": "object",
          "properties": {
            "color": {
              "description": "Border color for this side.",
              "type": "string"
            },
            "width": {
              "description": "Border width in pixels for this side.",
              "type": "number"
            },
            "style": {
              "description": "Border style for this side.",
              "type": "string",
              "enum": [
                "solid",
                "dashed",
                "dotted",
                "none"
              ]
            }
          }
        },
        "right": {
          "description": "Right border override for this cell.",
          "type": "object",
          "properties": {
            "color": {
              "description": "Border color for this side.",
              "type": "string"
            },
            "width": {
              "description": "Border width in pixels for this side.",
              "type": "number"
            },
            "style": {
              "description": "Border style for this side.",
              "type": "string",
              "enum": [
                "solid",
                "dashed",
                "dotted",
                "none"
              ]
            }
          }
        },
        "bottom": {
          "description": "Bottom border override for this cell.",
          "type": "object",
          "properties": {
            "color": {
              "description": "Border color for this side.",
              "type": "string"
            },
            "width": {
              "description": "Border width in pixels for this side.",
              "type": "number"
            },
            "style": {
              "description": "Border style for this side.",
              "type": "string",
              "enum": [
                "solid",
                "dashed",
                "dotted",
                "none"
              ]
            }
          }
        },
        "left": {
          "description": "Left border override for this cell.",
          "type": "object",
          "properties": {
            "color": {
              "description": "Border color for this side.",
              "type": "string"
            },
            "width": {
              "description": "Border width in pixels for this side.",
              "type": "number"
            },
            "style": {
              "description": "Border style for this side.",
              "type": "string",
              "enum": [
                "solid",
                "dashed",
                "dotted",
                "none"
              ]
            }
          }
        }
      }
    },
    "fontSize": {
      "description": "Font size in pixels (inherits from the table when omitted).",
      "type": "number"
    },
    "fontFamily": {
      "description": "Font family name (inherits from the table when omitted).",
      "type": "string"
    },
    "fontWeight": {
      "description": "Font weight: 'normal', 'bold', or numeric string (inherits from the table when omitted).",
      "type": "string"
    },
    "fontStyle": {
      "description": "Font style: 'normal' or 'italic' (inherits from the table when omitted).",
      "type": "string"
    },
    "textDecoration": {
      "description": "Text decoration, e.g. underline, line-through (inherits from the table when omitted).",
      "type": "string"
    },
    "textTransform": {
      "description": "Text transform: uppercase, lowercase, capitalize, none (inherits from the table when omitted).",
      "type": "string"
    },
    "fill": {
      "description": "Text color (inherits from the table when omitted).",
      "type": "string"
    },
    "align": {
      "description": "Horizontal alignment: left, center, right, justify (inherits from the table when omitted).",
      "type": "string"
    },
    "verticalAlign": {
      "description": "Vertical alignment: top, middle, bottom (inherits from the table when omitted).",
      "type": "string"
    },
    "lineHeight": {
      "description": "Line height multiplier or 'auto' (inherits from the table when omitted).",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "letterSpacing": {
      "description": "Letter spacing as a fraction of font size (inherits from the table when omitted).",
      "type": "number"
    },
    "strokeWidth": {
      "description": "Stroke width in pixels (inherits from the table when omitted).",
      "type": "number"
    },
    "stroke": {
      "description": "Stroke color (inherits from the table when omitted).",
      "type": "string"
    },
    "cellBackground": {
      "description": "Cell background color (inherits from the table when omitted).",
      "type": "string"
    },
    "cellPadding": {
      "description": "Cell padding in pixels (inherits from the table when omitted).",
      "type": "number"
    }
  },
  "required": [
    "id"
  ]
}
```

## Related Definitions [#related-definitions]

* [CellBorders](./cell-borders)
* [BorderSide](./border-side)


---

# TableElement
URL: https://polotno.com/docs/schema/table-element



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property          | Type                                              | Description                                                     |
| ----------------- | ------------------------------------------------- | --------------------------------------------------------------- |
| `id`              | `string`                                          | Unique identifier for the element.                              |
| `type`            | `"table"`                                         | Element type identifier.                                        |
| `name`            | `string`                                          | Display name for the element.                                   |
| `custom`          | `unknown`                                         | Custom data attached to the element.                            |
| `x`               | `number`                                          | X position in pixels.                                           |
| `y`               | `number`                                          | Y position in pixels.                                           |
| `width`           | `number`                                          | Width in pixels.                                                |
| `height`          | `number`                                          | Height in pixels.                                               |
| `rotation`        | `number`                                          | Rotation angle in degrees.                                      |
| `opacity`         | `number`                                          | Opacity level (0-1).                                            |
| `animations`      | Array\<[`Animation`](./animation)>                | Animation configurations.                                       |
| `visible`         | `boolean`                                         | Whether the element is visible.                                 |
| `draggable`       | `boolean`                                         | Whether the element can be dragged.                             |
| `resizable`       | `boolean`                                         | Whether the element can be resized.                             |
| `selectable`      | `boolean`                                         | Whether the element can be selected.                            |
| `removable`       | `boolean`                                         | Whether the element can be removed.                             |
| `contentEditable` | `boolean`                                         | Whether the element content can be edited.                      |
| `styleEditable`   | `boolean`                                         | Whether the element style can be edited.                        |
| `alwaysOnTop`     | `boolean`                                         | Whether the element stays on top of others.                     |
| `showInExport`    | `boolean`                                         | Whether the element appears in exports.                         |
| `rows`            | `number`                                          | Number of rows.                                                 |
| `cols`            | `number`                                          | Number of columns.                                              |
| `colWidths`       | Array\<`number`>                                  | Column width fractions (sum to 1).                              |
| `rowHeights`      | Array\<`number`>                                  | Row height fractions (sum to 1).                                |
| `cells`           | Array\<[`TableCell`](./table-cell)>               | Flat cell array in row-major order.                             |
| `borderColor`     | `string`                                          | Default border color for the table grid.                        |
| `borderWidth`     | `number`                                          | Default border width in pixels.                                 |
| `borderStyle`     | `"solid"` \| `"dashed"` \| `"dotted"` \| `"none"` | Default border style.                                           |
| `fontSize`        | `number`                                          | Default font size in pixels for cells.                          |
| `fontFamily`      | `string`                                          | Default font family name for cells.                             |
| `fontWeight`      | `string`                                          | Default font weight: 'normal', 'bold', or numeric string.       |
| `fontStyle`       | `string`                                          | Default font style: 'normal' or 'italic'.                       |
| `textDecoration`  | `string`                                          | Default text decoration (e.g. underline, line-through).         |
| `textTransform`   | `string`                                          | Default text transform: uppercase, lowercase, capitalize, none. |
| `fill`            | `string`                                          | Default text color for cells.                                   |
| `align`           | `string`                                          | Default horizontal alignment: left, center, right, justify.     |
| `verticalAlign`   | `string`                                          | Default vertical alignment: top, middle, bottom.                |
| `lineHeight`      | `number` \| `string`                              | Default line height multiplier or 'auto'.                       |
| `letterSpacing`   | `number`                                          | Default letter spacing as a fraction of font size.              |
| `strokeWidth`     | `number`                                          | Default stroke width in pixels.                                 |
| `stroke`          | `string`                                          | Default stroke color.                                           |
| `cellBackground`  | `string`                                          | Default cell background color.                                  |
| `cellPadding`     | `number`                                          | Default cell padding in pixels.                                 |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the element."
    },
    "type": {
      "type": "string",
      "const": "table",
      "description": "Element type identifier."
    },
    "name": {
      "default": "",
      "description": "Display name for the element.",
      "type": "string"
    },
    "custom": {
      "description": "Custom data attached to the element."
    },
    "x": {
      "default": 0,
      "description": "X position in pixels.",
      "type": "number"
    },
    "y": {
      "default": 0,
      "description": "Y position in pixels.",
      "type": "number"
    },
    "width": {
      "default": 300,
      "description": "Width in pixels.",
      "type": "number"
    },
    "height": {
      "default": 200,
      "description": "Height in pixels.",
      "type": "number"
    },
    "rotation": {
      "default": 0,
      "description": "Rotation angle in degrees.",
      "type": "number"
    },
    "opacity": {
      "default": 1,
      "description": "Opacity level (0-1).",
      "type": "number"
    },
    "animations": {
      "default": [],
      "description": "Animation configurations.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "delay": {
            "default": 0,
            "description": "Delay before the animation starts, in milliseconds.",
            "type": "number"
          },
          "duration": {
            "default": 500,
            "description": "Animation duration in milliseconds.",
            "type": "number"
          },
          "enabled": {
            "default": true,
            "description": "Whether the animation is enabled.",
            "type": "boolean"
          },
          "type": {
            "type": "string",
            "enum": [
              "enter",
              "exit",
              "loop"
            ],
            "description": "Animation phase."
          },
          "name": {
            "default": "none",
            "description": "Animation name identifier.",
            "type": "string"
          },
          "data": {
            "default": {},
            "description": "Animation-specific data."
          }
        },
        "required": [
          "type"
        ]
      }
    },
    "visible": {
      "default": true,
      "description": "Whether the element is visible.",
      "type": "boolean"
    },
    "draggable": {
      "default": true,
      "description": "Whether the element can be dragged.",
      "type": "boolean"
    },
    "resizable": {
      "default": true,
      "description": "Whether the element can be resized.",
      "type": "boolean"
    },
    "selectable": {
      "default": true,
      "description": "Whether the element can be selected.",
      "type": "boolean"
    },
    "removable": {
      "default": true,
      "description": "Whether the element can be removed.",
      "type": "boolean"
    },
    "contentEditable": {
      "default": true,
      "description": "Whether the element content can be edited.",
      "type": "boolean"
    },
    "styleEditable": {
      "default": true,
      "description": "Whether the element style can be edited.",
      "type": "boolean"
    },
    "alwaysOnTop": {
      "default": false,
      "description": "Whether the element stays on top of others.",
      "type": "boolean"
    },
    "showInExport": {
      "default": true,
      "description": "Whether the element appears in exports.",
      "type": "boolean"
    },
    "rows": {
      "default": 3,
      "description": "Number of rows.",
      "type": "number"
    },
    "cols": {
      "default": 3,
      "description": "Number of columns.",
      "type": "number"
    },
    "colWidths": {
      "default": [],
      "description": "Column width fractions (sum to 1).",
      "type": "array",
      "items": {
        "type": "number"
      }
    },
    "rowHeights": {
      "default": [],
      "description": "Row height fractions (sum to 1).",
      "type": "array",
      "items": {
        "type": "number"
      }
    },
    "cells": {
      "default": [],
      "description": "Flat cell array in row-major order.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the cell."
          },
          "type": {
            "default": "tablecell",
            "description": "Cell type identifier.",
            "type": "string",
            "const": "tablecell"
          },
          "text": {
            "default": "",
            "description": "Visible text shown in the cell.",
            "type": "string"
          },
          "opacity": {
            "description": "Opacity level (0-1).",
            "type": "number"
          },
          "rowSpan": {
            "description": "Number of rows this cell spans.",
            "type": "number"
          },
          "colSpan": {
            "description": "Number of columns this cell spans.",
            "type": "number"
          },
          "mergedInto": {
            "description": "Id of the cell this one is merged into, if any.",
            "type": "string"
          },
          "name": {
            "description": "Display name for the cell.",
            "type": "string"
          },
          "custom": {
            "description": "Custom data attached to the cell."
          },
          "borders": {
            "description": "Per-side border overrides for this cell.",
            "type": "object",
            "properties": {
              "top": {
                "description": "Top border override for this cell.",
                "type": "object",
                "properties": {
                  "color": {
                    "description": "Border color for this side.",
                    "type": "string"
                  },
                  "width": {
                    "description": "Border width in pixels for this side.",
                    "type": "number"
                  },
                  "style": {
                    "description": "Border style for this side.",
                    "type": "string",
                    "enum": [
                      "solid",
                      "dashed",
                      "dotted",
                      "none"
                    ]
                  }
                }
              },
              "right": {
                "description": "Right border override for this cell.",
                "type": "object",
                "properties": {
                  "color": {
                    "description": "Border color for this side.",
                    "type": "string"
                  },
                  "width": {
                    "description": "Border width in pixels for this side.",
                    "type": "number"
                  },
                  "style": {
                    "description": "Border style for this side.",
                    "type": "string",
                    "enum": [
                      "solid",
                      "dashed",
                      "dotted",
                      "none"
                    ]
                  }
                }
              },
              "bottom": {
                "description": "Bottom border override for this cell.",
                "type": "object",
                "properties": {
                  "color": {
                    "description": "Border color for this side.",
                    "type": "string"
                  },
                  "width": {
                    "description": "Border width in pixels for this side.",
                    "type": "number"
                  },
                  "style": {
                    "description": "Border style for this side.",
                    "type": "string",
                    "enum": [
                      "solid",
                      "dashed",
                      "dotted",
                      "none"
                    ]
                  }
                }
              },
              "left": {
                "description": "Left border override for this cell.",
                "type": "object",
                "properties": {
                  "color": {
                    "description": "Border color for this side.",
                    "type": "string"
                  },
                  "width": {
                    "description": "Border width in pixels for this side.",
                    "type": "number"
                  },
                  "style": {
                    "description": "Border style for this side.",
                    "type": "string",
                    "enum": [
                      "solid",
                      "dashed",
                      "dotted",
                      "none"
                    ]
                  }
                }
              }
            }
          },
          "fontSize": {
            "description": "Font size in pixels (inherits from the table when omitted).",
            "type": "number"
          },
          "fontFamily": {
            "description": "Font family name (inherits from the table when omitted).",
            "type": "string"
          },
          "fontWeight": {
            "description": "Font weight: 'normal', 'bold', or numeric string (inherits from the table when omitted).",
            "type": "string"
          },
          "fontStyle": {
            "description": "Font style: 'normal' or 'italic' (inherits from the table when omitted).",
            "type": "string"
          },
          "textDecoration": {
            "description": "Text decoration, e.g. underline, line-through (inherits from the table when omitted).",
            "type": "string"
          },
          "textTransform": {
            "description": "Text transform: uppercase, lowercase, capitalize, none (inherits from the table when omitted).",
            "type": "string"
          },
          "fill": {
            "description": "Text color (inherits from the table when omitted).",
            "type": "string"
          },
          "align": {
            "description": "Horizontal alignment: left, center, right, justify (inherits from the table when omitted).",
            "type": "string"
          },
          "verticalAlign": {
            "description": "Vertical alignment: top, middle, bottom (inherits from the table when omitted).",
            "type": "string"
          },
          "lineHeight": {
            "description": "Line height multiplier or 'auto' (inherits from the table when omitted).",
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ]
          },
          "letterSpacing": {
            "description": "Letter spacing as a fraction of font size (inherits from the table when omitted).",
            "type": "number"
          },
          "strokeWidth": {
            "description": "Stroke width in pixels (inherits from the table when omitted).",
            "type": "number"
          },
          "stroke": {
            "description": "Stroke color (inherits from the table when omitted).",
            "type": "string"
          },
          "cellBackground": {
            "description": "Cell background color (inherits from the table when omitted).",
            "type": "string"
          },
          "cellPadding": {
            "description": "Cell padding in pixels (inherits from the table when omitted).",
            "type": "number"
          }
        },
        "required": [
          "id"
        ]
      }
    },
    "borderColor": {
      "default": "#000000",
      "description": "Default border color for the table grid.",
      "type": "string"
    },
    "borderWidth": {
      "default": 1,
      "description": "Default border width in pixels.",
      "type": "number"
    },
    "borderStyle": {
      "default": "solid",
      "description": "Default border style.",
      "type": "string",
      "enum": [
        "solid",
        "dashed",
        "dotted",
        "none"
      ]
    },
    "fontSize": {
      "default": 30,
      "description": "Default font size in pixels for cells.",
      "type": "number"
    },
    "fontFamily": {
      "default": "Roboto",
      "description": "Default font family name for cells.",
      "type": "string"
    },
    "fontWeight": {
      "default": "normal",
      "description": "Default font weight: 'normal', 'bold', or numeric string.",
      "type": "string"
    },
    "fontStyle": {
      "default": "normal",
      "description": "Default font style: 'normal' or 'italic'.",
      "type": "string"
    },
    "textDecoration": {
      "default": "",
      "description": "Default text decoration (e.g. underline, line-through).",
      "type": "string"
    },
    "textTransform": {
      "default": "none",
      "description": "Default text transform: uppercase, lowercase, capitalize, none.",
      "type": "string"
    },
    "fill": {
      "default": "black",
      "description": "Default text color for cells.",
      "type": "string"
    },
    "align": {
      "default": "center",
      "description": "Default horizontal alignment: left, center, right, justify.",
      "type": "string"
    },
    "verticalAlign": {
      "default": "middle",
      "description": "Default vertical alignment: top, middle, bottom.",
      "type": "string"
    },
    "lineHeight": {
      "default": 1.2,
      "description": "Default line height multiplier or 'auto'.",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "letterSpacing": {
      "default": 0,
      "description": "Default letter spacing as a fraction of font size.",
      "type": "number"
    },
    "strokeWidth": {
      "default": 0,
      "description": "Default stroke width in pixels.",
      "type": "number"
    },
    "stroke": {
      "default": "black",
      "description": "Default stroke color.",
      "type": "string"
    },
    "cellBackground": {
      "default": "transparent",
      "description": "Default cell background color.",
      "type": "string"
    },
    "cellPadding": {
      "default": 4,
      "description": "Default cell padding in pixels.",
      "type": "number"
    }
  },
  "required": [
    "id",
    "type"
  ]
}
```

## Related Definitions [#related-definitions]

* [Animation](./animation)
* [TableCell](./table-cell)
* [CellBorders](./cell-borders)
* [BorderSide](./border-side)


---

# TextElement
URL: https://polotno.com/docs/schema/text-element



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property                 | Type                               | Description                                                 |        |       |           |
| ------------------------ | ---------------------------------- | ----------------------------------------------------------- | ------ | ----- | --------- |
| `id`                     | `string`                           | Unique identifier for the element.                          |        |       |           |
| `type`                   | `"text"`                           | *No description provided*                                   |        |       |           |
| `name`                   | `string`                           | Display name for the element.                               |        |       |           |
| `custom`                 | `unknown`                          | Custom data attached to the element.                        |        |       |           |
| `x`                      | `number`                           | X position in pixels.                                       |        |       |           |
| `y`                      | `number`                           | Y position in pixels.                                       |        |       |           |
| `width`                  | `number`                           | Width in pixels.                                            |        |       |           |
| `height`                 | `number`                           | Height in pixels (0 until measured/rendered).               |        |       |           |
| `rotation`               | `number`                           | Rotation angle in degrees.                                  |        |       |           |
| `opacity`                | `number`                           | Opacity level (0-1).                                        |        |       |           |
| `animations`             | Array\<[`Animation`](./animation)> | Animation configurations.                                   |        |       |           |
| `blurEnabled`            | `boolean`                          | Whether blur effect is enabled.                             |        |       |           |
| `blurRadius`             | `number`                           | Blur radius in pixels.                                      |        |       |           |
| `brightnessEnabled`      | `boolean`                          | Whether brightness effect is enabled.                       |        |       |           |
| `brightness`             | `number`                           | Brightness level (-1 to 1).                                 |        |       |           |
| `sepiaEnabled`           | `boolean`                          | Whether sepia effect is enabled.                            |        |       |           |
| `grayscaleEnabled`       | `boolean`                          | Whether grayscale effect is enabled.                        |        |       |           |
| `filters`                | `object`                           | Applied image filters keyed by filter name.                 |        |       |           |
| `shadowEnabled`          | `boolean`                          | Whether shadow is enabled.                                  |        |       |           |
| `shadowBlur`             | `number`                           | Shadow blur radius in pixels.                               |        |       |           |
| `shadowOffsetX`          | `number`                           | Shadow horizontal offset in pixels.                         |        |       |           |
| `shadowOffsetY`          | `number`                           | Shadow vertical offset in pixels.                           |        |       |           |
| `shadowColor`            | `string`                           | Shadow color.                                               |        |       |           |
| `shadowOpacity`          | `number`                           | Shadow opacity (0-1).                                       |        |       |           |
| `visible`                | `boolean`                          | Whether the element is visible.                             |        |       |           |
| `draggable`              | `boolean`                          | Whether the element can be dragged.                         |        |       |           |
| `resizable`              | `boolean`                          | Whether the element can be resized.                         |        |       |           |
| `selectable`             | `boolean`                          | Whether the element can be selected.                        |        |       |           |
| `removable`              | `boolean`                          | Whether the element can be removed.                         |        |       |           |
| `contentEditable`        | `boolean`                          | Whether the element content can be edited.                  |        |       |           |
| `styleEditable`          | `boolean`                          | Whether the element style can be edited.                    |        |       |           |
| `alwaysOnTop`            | `boolean`                          | Whether the element stays on top of others.                 |        |       |           |
| `showInExport`           | `boolean`                          | Whether the element appears in exports.                     |        |       |           |
| `text`                   | `string`                           | Visible text shown on canvas.                               |        |       |           |
| `placeholder`            | `string`                           | Placeholder text shown when empty.                          |        |       |           |
| `fontSize`               | `number`                           | Font size in pixels.                                        |        |       |           |
| `fontFamily`             | `string`                           | Font family name.                                           |        |       |           |
| `fontStyle`              | `string`                           | Font style: 'normal' or 'italic'.                           |        |       |           |
| `fontWeight`             | `string`                           | Font weight: 'normal', 'bold', or numeric string.           |        |       |           |
| `textDecoration`         | `string`                           | Text decoration (e.g. underline, line-through).             |        |       |           |
| `textTransform`          | `string`                           | Text transform: uppercase, lowercase, capitalize, none.     |        |       |           |
| `fill`                   | `string`                           | Text color.                                                 |        |       |           |
| `align`                  | `string`                           | Horizontal alignment (commonly left                         | center | right | justify). |
| `verticalAlign`          | `string`                           | Vertical alignment: top, middle, bottom.                    |        |       |           |
| `strokeWidth`            | `number`                           | Stroke width in pixels.                                     |        |       |           |
| `stroke`                 | `string`                           | Stroke color.                                               |        |       |           |
| `strokeLineJoin`         | `string`                           | Stroke corner join: round, miter, bevel.                    |        |       |           |
| `lineHeight`             | `number` \| `string`               | Line height multiplier or 'auto'.                           |        |       |           |
| `letterSpacing`          | `number`                           | Letter spacing as a fraction of font size.                  |        |       |           |
| `backgroundEnabled`      | `boolean`                          | Whether the text background is enabled.                     |        |       |           |
| `backgroundColor`        | `string`                           | Text background color.                                      |        |       |           |
| `backgroundOpacity`      | `number`                           | Text background opacity (0-1).                              |        |       |           |
| `backgroundCornerRadius` | `number`                           | Text background corner radius.                              |        |       |           |
| `backgroundPadding`      | `number`                           | Text background padding.                                    |        |       |           |
| `curveEnabled`           | `boolean`                          | Whether the text curve effect is enabled.                   |        |       |           |
| `curvePower`             | `number`                           | Text curve power (-1 to 1, 0 = straight).                   |        |       |           |
| `legacyBackground`       | `boolean`                          | Internal compatibility flag stamped by the v2→v3 migration. |        |       |           |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the element."
    },
    "type": {
      "type": "string",
      "const": "text"
    },
    "name": {
      "default": "",
      "description": "Display name for the element.",
      "type": "string"
    },
    "custom": {
      "description": "Custom data attached to the element."
    },
    "x": {
      "default": 0,
      "description": "X position in pixels.",
      "type": "number"
    },
    "y": {
      "default": 0,
      "description": "Y position in pixels.",
      "type": "number"
    },
    "width": {
      "default": 100,
      "description": "Width in pixels.",
      "type": "number"
    },
    "height": {
      "default": 0,
      "description": "Height in pixels (0 until measured/rendered).",
      "type": "number"
    },
    "rotation": {
      "default": 0,
      "description": "Rotation angle in degrees.",
      "type": "number"
    },
    "opacity": {
      "default": 1,
      "description": "Opacity level (0-1).",
      "type": "number"
    },
    "animations": {
      "default": [],
      "description": "Animation configurations.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "delay": {
            "default": 0,
            "description": "Delay before the animation starts, in milliseconds.",
            "type": "number"
          },
          "duration": {
            "default": 500,
            "description": "Animation duration in milliseconds.",
            "type": "number"
          },
          "enabled": {
            "default": true,
            "description": "Whether the animation is enabled.",
            "type": "boolean"
          },
          "type": {
            "type": "string",
            "enum": [
              "enter",
              "exit",
              "loop"
            ],
            "description": "Animation phase."
          },
          "name": {
            "default": "none",
            "description": "Animation name identifier.",
            "type": "string"
          },
          "data": {
            "default": {},
            "description": "Animation-specific data."
          }
        },
        "required": [
          "type"
        ]
      }
    },
    "blurEnabled": {
      "default": false,
      "description": "Whether blur effect is enabled.",
      "type": "boolean"
    },
    "blurRadius": {
      "default": 10,
      "description": "Blur radius in pixels.",
      "type": "number"
    },
    "brightnessEnabled": {
      "default": false,
      "description": "Whether brightness effect is enabled.",
      "type": "boolean"
    },
    "brightness": {
      "default": 0,
      "description": "Brightness level (-1 to 1).",
      "type": "number"
    },
    "sepiaEnabled": {
      "default": false,
      "description": "Whether sepia effect is enabled.",
      "type": "boolean"
    },
    "grayscaleEnabled": {
      "default": false,
      "description": "Whether grayscale effect is enabled.",
      "type": "boolean"
    },
    "filters": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "intensity": {
            "default": 1,
            "description": "Filter intensity (-1 to 1).",
            "type": "number"
          }
        }
      },
      "description": "Applied image filters keyed by filter name."
    },
    "shadowEnabled": {
      "default": false,
      "description": "Whether shadow is enabled.",
      "type": "boolean"
    },
    "shadowBlur": {
      "default": 5,
      "description": "Shadow blur radius in pixels.",
      "type": "number"
    },
    "shadowOffsetX": {
      "default": 0,
      "description": "Shadow horizontal offset in pixels.",
      "type": "number"
    },
    "shadowOffsetY": {
      "default": 0,
      "description": "Shadow vertical offset in pixels.",
      "type": "number"
    },
    "shadowColor": {
      "default": "black",
      "description": "Shadow color.",
      "type": "string"
    },
    "shadowOpacity": {
      "default": 1,
      "description": "Shadow opacity (0-1).",
      "type": "number"
    },
    "visible": {
      "default": true,
      "description": "Whether the element is visible.",
      "type": "boolean"
    },
    "draggable": {
      "default": true,
      "description": "Whether the element can be dragged.",
      "type": "boolean"
    },
    "resizable": {
      "default": true,
      "description": "Whether the element can be resized.",
      "type": "boolean"
    },
    "selectable": {
      "default": true,
      "description": "Whether the element can be selected.",
      "type": "boolean"
    },
    "removable": {
      "default": true,
      "description": "Whether the element can be removed.",
      "type": "boolean"
    },
    "contentEditable": {
      "default": true,
      "description": "Whether the element content can be edited.",
      "type": "boolean"
    },
    "styleEditable": {
      "default": true,
      "description": "Whether the element style can be edited.",
      "type": "boolean"
    },
    "alwaysOnTop": {
      "default": false,
      "description": "Whether the element stays on top of others.",
      "type": "boolean"
    },
    "showInExport": {
      "default": true,
      "description": "Whether the element appears in exports.",
      "type": "boolean"
    },
    "text": {
      "default": "",
      "description": "Visible text shown on canvas.",
      "type": "string"
    },
    "placeholder": {
      "default": "",
      "description": "Placeholder text shown when empty.",
      "type": "string"
    },
    "fontSize": {
      "default": 14,
      "description": "Font size in pixels.",
      "type": "number"
    },
    "fontFamily": {
      "default": "Roboto",
      "description": "Font family name.",
      "type": "string"
    },
    "fontStyle": {
      "default": "normal",
      "description": "Font style: 'normal' or 'italic'.",
      "type": "string"
    },
    "fontWeight": {
      "default": "normal",
      "description": "Font weight: 'normal', 'bold', or numeric string.",
      "type": "string"
    },
    "textDecoration": {
      "default": "",
      "description": "Text decoration (e.g. underline, line-through).",
      "type": "string"
    },
    "textTransform": {
      "default": "none",
      "description": "Text transform: uppercase, lowercase, capitalize, none.",
      "type": "string"
    },
    "fill": {
      "default": "black",
      "description": "Text color.",
      "type": "string"
    },
    "align": {
      "default": "center",
      "description": "Horizontal alignment (commonly left | center | right | justify).",
      "type": "string"
    },
    "verticalAlign": {
      "default": "top",
      "description": "Vertical alignment: top, middle, bottom.",
      "type": "string"
    },
    "strokeWidth": {
      "default": 0,
      "description": "Stroke width in pixels.",
      "type": "number"
    },
    "stroke": {
      "default": "black",
      "description": "Stroke color.",
      "type": "string"
    },
    "strokeLineJoin": {
      "default": "round",
      "description": "Stroke corner join: round, miter, bevel.",
      "type": "string"
    },
    "lineHeight": {
      "default": 1.2,
      "description": "Line height multiplier or 'auto'.",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "letterSpacing": {
      "default": 0,
      "description": "Letter spacing as a fraction of font size.",
      "type": "number"
    },
    "backgroundEnabled": {
      "default": false,
      "description": "Whether the text background is enabled.",
      "type": "boolean"
    },
    "backgroundColor": {
      "default": "#7ED321",
      "description": "Text background color.",
      "type": "string"
    },
    "backgroundOpacity": {
      "default": 1,
      "description": "Text background opacity (0-1).",
      "type": "number"
    },
    "backgroundCornerRadius": {
      "default": 0.5,
      "description": "Text background corner radius.",
      "type": "number"
    },
    "backgroundPadding": {
      "default": 0.5,
      "description": "Text background padding.",
      "type": "number"
    },
    "curveEnabled": {
      "default": false,
      "description": "Whether the text curve effect is enabled.",
      "type": "boolean"
    },
    "curvePower": {
      "default": 0.5,
      "description": "Text curve power (-1 to 1, 0 = straight).",
      "type": "number"
    },
    "legacyBackground": {
      "description": "Internal compatibility flag stamped by the v2→v3 migration.",
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "type"
  ]
}
```

## Related Definitions [#related-definitions]

* [Animation](./animation)


---

# VideoElement
URL: https://polotno.com/docs/schema/video-element



## Type Information [#type-information]

**Base Type:** `object`

## Properties [#properties]

| Property            | Type                               | Description                                     |
| ------------------- | ---------------------------------- | ----------------------------------------------- |
| `id`                | `string`                           | Unique identifier for the element.              |
| `type`              | `"video"`                          | *No description provided*                       |
| `name`              | `string`                           | Display name for the element.                   |
| `custom`            | `unknown`                          | Custom data attached to the element.            |
| `x`                 | `number`                           | X position in pixels.                           |
| `y`                 | `number`                           | Y position in pixels.                           |
| `width`             | `number`                           | Width in pixels.                                |
| `height`            | `number`                           | Height in pixels.                               |
| `rotation`          | `number`                           | Rotation angle in degrees.                      |
| `opacity`           | `number`                           | Opacity level (0-1).                            |
| `animations`        | Array\<[`Animation`](./animation)> | Animation configurations.                       |
| `blurEnabled`       | `boolean`                          | Whether blur effect is enabled.                 |
| `blurRadius`        | `number`                           | Blur radius in pixels.                          |
| `brightnessEnabled` | `boolean`                          | Whether brightness effect is enabled.           |
| `brightness`        | `number`                           | Brightness level (-1 to 1).                     |
| `sepiaEnabled`      | `boolean`                          | Whether sepia effect is enabled.                |
| `grayscaleEnabled`  | `boolean`                          | Whether grayscale effect is enabled.            |
| `filters`           | `object`                           | Applied image filters keyed by filter name.     |
| `shadowEnabled`     | `boolean`                          | Whether shadow is enabled.                      |
| `shadowBlur`        | `number`                           | Shadow blur radius in pixels.                   |
| `shadowOffsetX`     | `number`                           | Shadow horizontal offset in pixels.             |
| `shadowOffsetY`     | `number`                           | Shadow vertical offset in pixels.               |
| `shadowColor`       | `string`                           | Shadow color.                                   |
| `shadowOpacity`     | `number`                           | Shadow opacity (0-1).                           |
| `visible`           | `boolean`                          | Whether the element is visible.                 |
| `draggable`         | `boolean`                          | Whether the element can be dragged.             |
| `resizable`         | `boolean`                          | Whether the element can be resized.             |
| `selectable`        | `boolean`                          | Whether the element can be selected.            |
| `removable`         | `boolean`                          | Whether the element can be removed.             |
| `contentEditable`   | `boolean`                          | Whether the element content can be edited.      |
| `styleEditable`     | `boolean`                          | Whether the element style can be edited.        |
| `alwaysOnTop`       | `boolean`                          | Whether the element stays on top of others.     |
| `showInExport`      | `boolean`                          | Whether the element appears in exports.         |
| `src`               | `string`                           | URL or data URI of the image file.              |
| `cropX`             | `number`                           | Crop X offset as a fraction (0-1).              |
| `cropY`             | `number`                           | Crop Y offset as a fraction (0-1).              |
| `cropWidth`         | `number`                           | Crop width as a fraction (0-1).                 |
| `cropHeight`        | `number`                           | Crop height as a fraction (0-1).                |
| `cornerRadius`      | `number`                           | Corner radius in pixels.                        |
| `flipX`             | `boolean`                          | Whether the image is flipped horizontally.      |
| `flipY`             | `boolean`                          | Whether the image is flipped vertically.        |
| `clipSrc`           | `string`                           | URL or data URI for a clipping mask.            |
| `borderColor`       | `string`                           | Border color.                                   |
| `borderSize`        | `number`                           | Border width in pixels.                         |
| `keepRatio`         | `boolean`                          | Whether to maintain aspect ratio when resizing. |
| `stretchEnabled`    | `boolean`                          | Whether stretch mode is enabled.                |
| `duration`          | `number`                           | Video duration in milliseconds.                 |
| `startTime`         | `number`                           | Start offset (0-1).                             |
| `endTime`           | `number`                           | End offset (0-1).                               |
| `volume`            | `number`                           | Volume (0-1).                                   |
| `speed`             | `number`                           | Playback speed multiplier (1 = normal).         |

## JSON Schema [#json-schema]

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the element."
    },
    "type": {
      "type": "string",
      "const": "video"
    },
    "name": {
      "default": "",
      "description": "Display name for the element.",
      "type": "string"
    },
    "custom": {
      "description": "Custom data attached to the element."
    },
    "x": {
      "default": 0,
      "description": "X position in pixels.",
      "type": "number"
    },
    "y": {
      "default": 0,
      "description": "Y position in pixels.",
      "type": "number"
    },
    "width": {
      "default": 100,
      "description": "Width in pixels.",
      "type": "number"
    },
    "height": {
      "default": 100,
      "description": "Height in pixels.",
      "type": "number"
    },
    "rotation": {
      "default": 0,
      "description": "Rotation angle in degrees.",
      "type": "number"
    },
    "opacity": {
      "default": 1,
      "description": "Opacity level (0-1).",
      "type": "number"
    },
    "animations": {
      "default": [],
      "description": "Animation configurations.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "delay": {
            "default": 0,
            "description": "Delay before the animation starts, in milliseconds.",
            "type": "number"
          },
          "duration": {
            "default": 500,
            "description": "Animation duration in milliseconds.",
            "type": "number"
          },
          "enabled": {
            "default": true,
            "description": "Whether the animation is enabled.",
            "type": "boolean"
          },
          "type": {
            "type": "string",
            "enum": [
              "enter",
              "exit",
              "loop"
            ],
            "description": "Animation phase."
          },
          "name": {
            "default": "none",
            "description": "Animation name identifier.",
            "type": "string"
          },
          "data": {
            "default": {},
            "description": "Animation-specific data."
          }
        },
        "required": [
          "type"
        ]
      }
    },
    "blurEnabled": {
      "default": false,
      "description": "Whether blur effect is enabled.",
      "type": "boolean"
    },
    "blurRadius": {
      "default": 10,
      "description": "Blur radius in pixels.",
      "type": "number"
    },
    "brightnessEnabled": {
      "default": false,
      "description": "Whether brightness effect is enabled.",
      "type": "boolean"
    },
    "brightness": {
      "default": 0,
      "description": "Brightness level (-1 to 1).",
      "type": "number"
    },
    "sepiaEnabled": {
      "default": false,
      "description": "Whether sepia effect is enabled.",
      "type": "boolean"
    },
    "grayscaleEnabled": {
      "default": false,
      "description": "Whether grayscale effect is enabled.",
      "type": "boolean"
    },
    "filters": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "intensity": {
            "default": 1,
            "description": "Filter intensity (-1 to 1).",
            "type": "number"
          }
        }
      },
      "description": "Applied image filters keyed by filter name."
    },
    "shadowEnabled": {
      "default": false,
      "description": "Whether shadow is enabled.",
      "type": "boolean"
    },
    "shadowBlur": {
      "default": 5,
      "description": "Shadow blur radius in pixels.",
      "type": "number"
    },
    "shadowOffsetX": {
      "default": 0,
      "description": "Shadow horizontal offset in pixels.",
      "type": "number"
    },
    "shadowOffsetY": {
      "default": 0,
      "description": "Shadow vertical offset in pixels.",
      "type": "number"
    },
    "shadowColor": {
      "default": "black",
      "description": "Shadow color.",
      "type": "string"
    },
    "shadowOpacity": {
      "default": 1,
      "description": "Shadow opacity (0-1).",
      "type": "number"
    },
    "visible": {
      "default": true,
      "description": "Whether the element is visible.",
      "type": "boolean"
    },
    "draggable": {
      "default": true,
      "description": "Whether the element can be dragged.",
      "type": "boolean"
    },
    "resizable": {
      "default": true,
      "description": "Whether the element can be resized.",
      "type": "boolean"
    },
    "selectable": {
      "default": true,
      "description": "Whether the element can be selected.",
      "type": "boolean"
    },
    "removable": {
      "default": true,
      "description": "Whether the element can be removed.",
      "type": "boolean"
    },
    "contentEditable": {
      "default": true,
      "description": "Whether the element content can be edited.",
      "type": "boolean"
    },
    "styleEditable": {
      "default": true,
      "description": "Whether the element style can be edited.",
      "type": "boolean"
    },
    "alwaysOnTop": {
      "default": false,
      "description": "Whether the element stays on top of others.",
      "type": "boolean"
    },
    "showInExport": {
      "default": true,
      "description": "Whether the element appears in exports.",
      "type": "boolean"
    },
    "src": {
      "default": "",
      "description": "URL or data URI of the image file.",
      "type": "string"
    },
    "cropX": {
      "default": 0,
      "description": "Crop X offset as a fraction (0-1).",
      "type": "number"
    },
    "cropY": {
      "default": 0,
      "description": "Crop Y offset as a fraction (0-1).",
      "type": "number"
    },
    "cropWidth": {
      "default": 1,
      "description": "Crop width as a fraction (0-1).",
      "type": "number"
    },
    "cropHeight": {
      "default": 1,
      "description": "Crop height as a fraction (0-1).",
      "type": "number"
    },
    "cornerRadius": {
      "default": 0,
      "description": "Corner radius in pixels.",
      "type": "number"
    },
    "flipX": {
      "default": false,
      "description": "Whether the image is flipped horizontally.",
      "type": "boolean"
    },
    "flipY": {
      "default": false,
      "description": "Whether the image is flipped vertically.",
      "type": "boolean"
    },
    "clipSrc": {
      "default": "",
      "description": "URL or data URI for a clipping mask.",
      "type": "string"
    },
    "borderColor": {
      "default": "black",
      "description": "Border color.",
      "type": "string"
    },
    "borderSize": {
      "default": 0,
      "description": "Border width in pixels.",
      "type": "number"
    },
    "keepRatio": {
      "default": false,
      "description": "Whether to maintain aspect ratio when resizing.",
      "type": "boolean"
    },
    "stretchEnabled": {
      "default": false,
      "description": "Whether stretch mode is enabled.",
      "type": "boolean"
    },
    "duration": {
      "default": 0,
      "description": "Video duration in milliseconds.",
      "type": "number"
    },
    "startTime": {
      "default": 0,
      "description": "Start offset (0-1).",
      "type": "number"
    },
    "endTime": {
      "default": 1,
      "description": "End offset (0-1).",
      "type": "number"
    },
    "volume": {
      "default": 1,
      "description": "Volume (0-1).",
      "type": "number"
    },
    "speed": {
      "default": 1,
      "description": "Playback speed multiplier (1 = normal).",
      "type": "number"
    }
  },
  "required": [
    "id",
    "type"
  ]
}
```

## Related Definitions [#related-definitions]

* [Animation](./animation)