Puck 0.22 doesn’t introduce any breaking changes, but it refreshes the styling system and tweaks a couple of defaults that are worth knowing about before you upgrade.

In this post, we will guide you through the steps for upgrading to Puck 0.22:

• Installing Puck 0.22
• Breaking changes
• New deprecations
• Notable changes
• Full changelog

If you encounter any bugs as you upgrade to Puck 0.22, please report them via GitHub.

For a list of all the new features added to Puck 0.22, check out the release blog post.

Installing Puck 0.22

Run the following command to install the latest version of Puck:

npm install @puckeditor/core@latest

pnpm add @puckeditor/core@latest

yarn add @puckeditor/core@latest

bun add @puckeditor/core@latest

Breaking changes

Puck 0.22 doesn’t introduce any breaking changes, so upgrading from Puck 0.21 won’t require updates to your existing integration.

New deprecations

No deprecations were introduced in this release.

Notable changes

Editor styles have changed

Puck 0.22 introduces a new theming API for the default editor UI.

As part of this work, Puck’s internal styles have been migrated to CSS custom properties. Most of this migration won’t be noticeable, but some of the default styles have changed slightly to keep the default UI consistent.

For the full list of style changes, see the theming styles commit. The main visible style changes are:

• Radio fields: radio options now use the same font size and spacing as other fields. Radio fields will be taller.
• Array field highlights: array fields now use the same focus and selection styles as the rest of the editor. The add icon is darker, expanded items have a stronger outline, and dragging outlines are more consistent with other selected states.
• Rich text fields: rich text fields now follow the same field hover and disabled states as other inputs. Their border now darkens on hover, and when disabled, their content uses the secondary text color.
• Select chevrons: select fields now render the chevron as an icon instead of an inline background image, and its color matches the field border color. The chevron will look lighter by default and slightly smaller.
• Component and slot overlays: slots and selected-component overlays now share the same selection styles. Their background is a little softer, and drag destination outlines no longer switch to a darker blue.

If these new styles don’t match your app’s design, you can override them using the theming API.

Replace old palette overrides with the new theming API

Before this release, some projects overrode Puck’s internal palette variables to work around the lack of a full theming API. This was never officially supported, but it was often the only lightweight option without replacing the default UI.

If you were doing that, switch to the documented theming tokens instead:

/* Before: overriding internal palette values */
.MyEditor {
  --puck-color-azure-04: #0d9488;
  --puck-color-azure-03: #0f766e;
}
 
/* After: overriding tokens */
.MyEditor {
  --puck-color-interactive: #0d9488;
  --puck-color-interactive-hover: #0f766e;
}

CSS now loads automatically

Puck now injects its stylesheet on demand at runtime. This means you no longer need to import @puckeditor/core/puck.css next to the editor:

// Before
import { Puck } from "@puckeditor/core";
import "@puckeditor/core/puck.css";
 
const Editor = () => <Puck data={data} config={config} />;
 
// After
import { Puck } from "@puckeditor/core";
 
const Editor = () => <Puck data={data} config={config} />;

Existing imports continue to work and remain the recommended way to load Puck’s CSS if you want to bundle it with your app to avoid runtime injection and a flash of unstyled content.

The Remix recipe has been removed from create-puck-app

The Remix v2 project has merged into React Router, and create-puck-app no longer ships the Remix templates. If you previously used one of those recipes, use the React Router recipe instead:

npx create-puck-app my-app
? Which recipe would you like to use?
> React Router

Full changelog

Check out the full changelog, including known issues, on the GitHub release.