Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PolotnoContainer
✓ import { PolotnoContainer } from 'polotno';
✗ const PolotnoContainer = require('polotno').PolotnoContainer;
Polotno is primarily designed for ES Module environments. CommonJS `require` is not officially supported for UI components and may lead to issues.
createStore
✓ import { createStore } from 'polotno/model/store';
✗ import createStore from 'polotno/model/store';
`createStore` is a named export from its specific module path. Direct default import is incorrect.
Toolbar
✓ import { Toolbar } from 'polotno/toolbar/toolbar';
✗ import { Toolbar } from 'polotno';
Many UI components are imported from specific sub-paths for better tree-shaking and modularity.
This quickstart initializes a basic Polotno design editor with a side panel, toolbar, and workspace, rendered as a React component. It sets up the core store, adds a default page, and includes necessary CSS. An API key is required.
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';
import '@blueprintjs/core/lib/css/blueprint.css'; // Polotno uses Blueprint.js styles
const store = createStore({
key: process.env.POLOTNO_API_KEY ?? 'YOUR_FREE_API_KEY_HERE',
showCredit: true // Set to false with a paid license to hide the back-link
});
// Add a default page to the store
store.addPage();
export const PolotnoEditor = () => {
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>
);
};
// Example of how to render it in a root (e.g., in index.tsx)
/*
const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
root.render(
<React.StrictMode>
<PolotnoEditor />
</React.StrictMode>
);
*/
Debug
Known issues
breakingPolotno currently relies on React 18.2.0. Using React 19 may cause dependency resolution issues or runtime errors like `Cannot read properties of undefined (reading 'ReactCurrentOwner')`.fixYou must explicitly override `react`, `react-dom`, and `react-konva` dependencies to force them to React 18 in your `package.json` to ensure compatibility. Refer to the official Polotno documentation for specific override configurations.
affects: >=2.0.0 with React >=19.0.0
gotchaA Polotno API key is required for production usage. While a free key is available for development, commercial use necessitates obtaining a license.fixRegister for an API key at Polotno's website. The `createStore` function requires the `key` option. Setting `showCredit: true` can display a back-link, which can be disabled with a paid license.
affects: All versions
gotchaIntegrating Polotno (a React-based library using MobX) into other JavaScript frameworks like Vue or Angular directly can lead to 'Maximum update depth exceeded' errors due to reactivity conflicts.fixIt is recommended to encapsulate the Polotno editor within its own isolated React component and then mount that React component into your host framework. For MobX reactivity with Vue, ensure proper `mobx-vue-lite` or `mobx-angular` integration and `Observer` wrapping.
affects: All versions when used with non-React frameworks
gotchaComplex text elements combined with multiple filter-based effects and animations can lead to significant memory usage, potentially causing browser tabs to become unresponsive or crash.fixMonitor memory usage with complex designs. Simplify text effects or animations where possible. Report specific reproducible cases to Polotno support.
affects: Reported in 2.38.2, potentially affecting similar versions.
gotchaWhen using `polotno-node` for server-side rendering, especially in environments like AWS Lambda, complex designs may require a substantial increase in allocated memory to prevent 'Out of Memory' errors or timeouts.fixIncrease the memory limit for your serverless function (e.g., AWS Lambda memory from default to maximum for complex designs). Optimize JSON payloads for simpler designs if possible.
affects: All `polotno-node` versions
Errors
Common errors & fixes
Could not resolve dependency: npm error peer react@"^18.2.0" from polotno@2.x.x
Attempting to install Polotno in a project using React 19, which has a conflicting peer dependency range.
fixAdd resolutions/overrides to your `package.json` to force `react`, `react-dom`, and `react-konva` (if used) to version 18.2.0, e.g., `"overrides": { "polotno": { "react": "18.2.0", "react-dom": "18.2.0", "react-konva": "^18.2.0" } }`. Uncaught TypeError: Cannot read properties of undefined (reading 'ReactCurrentOwner')
This error typically occurs when different versions of React are loaded, or React context is lost, often associated with React 19 compatibility issues.
fixEnsure all React-related packages (React, ReactDOM, Polotno, and any other UI libraries) resolve to the exact same React 18 version. Use package manager overrides as described for the `peer react` dependency error.
Error: Minified React error #185; Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate.
An infinite rendering loop, often when Polotno's MobX store reactivity conflicts with another framework's reactivity system (e.g., Vue 3) or when a React component's `setState` is called synchronously within its render or update phase without proper guarding.
fixWhen embedding Polotno in a non-React app, ensure the React part is isolated. For Vue 3, wrap the React editor mount point with `mobx-vue-lite`'s `Observer` component. Review component lifecycle for unintended state updates.
Memory leak / "Page unresponsive" when combining all text effects with an animation on a Text element.
Intensive rendering or state updates, particularly with complex text rendering, filters, and animations, can overwhelm browser resources.
fixSimplify design elements, reduce the number of simultaneous effects, or optimize animations for performance. Consider reporting the specific use case to Polotno support for potential library-level optimizations.
Audit
Dependencies
reactrequiredPeer dependency for Polotno's React components.
react-domrequiredPeer dependency for rendering Polotno's React components.