Polotno 4 Migration

Upgrade an existing Polotno 2 integration — adopt the new default UI, or keep the Blueprint look

Starting with Polotno 3.x (React 18) and 4.x (React 19), the editor ships with a new default UI built on its own design system. The previous Blueprint-based chrome still ships under polotno/blueprint/*, so you can either adopt the new UI or keep the old look.

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.

Path A — Adopt the new UI (recommended)

The component API is unchanged, so this is mostly a CSS swap.

1. Swap the CSS import

// Before
import '@blueprintjs/core/lib/css/blueprint.css';

// After
import 'polotno/ui.css';

2. Imports stay the same

The default Toolbar, SidePanel, PagesTimeline, and Workspace are already the new UI — your imports don't change:

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

Dark mode moved to the dark class (see Theme):

<body class="dark"></body>

4. Custom UI

If you built custom panels, toolbar buttons, or dialogs, rebuild them with polotno/primitives so they match the new design system.

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

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:

npm i @blueprintjs/core@6 @blueprintjs/icons@6 @blueprintjs/select@6

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.

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

polotno/blueprint.css bundles the Blueprint base styles and the Polotno chrome in one file.

// Before
import '@blueprintjs/core/lib/css/blueprint.css';
// After
import 'polotno/blueprint.css';

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 classNames, and index.html — including the dark-mode class:

<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.)

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.

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.

On this page