Forem: Chris Villa

Puck 0.19: Slots API & performance gains

Chris Villa — Tue, 10 Jun 2025 10:17:15 +0000

Puck 0.19 introduces the Slots API, the powerful successor to DropZones that lets you nest components using a field. This new approach allows you to define drop areas and their content programmatically using defaultProps and resolveData, enabling sophisticated patterns like component templates:

In addition to Slots, this release brings major performance improvements, a new metadata API for passing data into every component, and many quality-of-life upgrades.

In this post, we'll walk through everything new in Puck 0.19 and how to start using it:

What's new in Puck 0.19
Other changes
How to upgrade
Full changelog
Contributors

If you're upgrading from a previous version, be sure to check the upgrade guide for breaking changes and migration tips.

You can also find detailed docs for each new feature in our documentation.

What's new in Puck 0.19

Slots API

The slots API is a new field type you can use to render drop zones and nest components, replacing the DropZone API.

It works like any other field: you define it in your component config, and get access to its value in the component render function. The slot field is converted to a component that you can use to render the drop zone.

const config = {
  components: {
    Flexbox: {
      fields: {
        items: { type: "slot" },
      },
      render: ({ items: Items }) => {
        return <Items style={{ display: "flex" }} />;
      },
    },
  },
};

The slot component provided to the render function accepts most of the same props as the <DropZone /> component, making migration straightforward. See the slots documentation for a full breakdown of all available render props.

The components inside a slot are stored within the props of the parent component as an array of ComponentData, making slots completely portable and straightforward to work with for data transformation or schema validation.

{
  "type": "Flexbox",
  "props": {
    "id": "Flexbox-1",
    "items": [
      {
        "type": "Header",
        "props": {
          "id": "Header-2",
          "title": "Nested header"
        }
      }
    ]
  }
}

Since slots are regular fields, you can take full advantage of other field APIs, like defaultProps and resolveData, to programmatically set the components they contain.

const config = {
  components: {
    Flexbox: {
      fields: {
        items: { type: "slot" },
      },
      // Include a Header in this slot when the Flexbox is added to the page
      defaultProps: {
        items: [
          {
            type: "Header",
            props: {
              title: "Hello, world",
            },
          },
        ],
      },
      render: ({ items: Items }) => {
        return <Items style={{ display: "flex" }} />;
      },
    },
  },
};

Slots are now the recommended way to handle nested components in Puck. The DropZone component has been deprecated and will be removed in a future release.

Keep in mind: slots introduce a new model for representing components. Existing DropZone data, and advanced use-cases that parse or manipulate the Puck data payload may need to be updated. You can find guidance on how to migrate from DropZones to Slots in the upgrade guide.

New function: `walkTree`

The new walkTree utility recursively walks all slots in the entire tree of the data payload or a single ComponentData node, and optionally modifies the nodes.

import { walkTree } from "@measured/puck";

const transformedData = walkTree(data, config, (nestedComponents) => {
  // Add the "example" prop to all children
  return nestedComponents.map((child) => ({
    ...child,
    props: { ...child.props, example: "Hello, world" },
  }));
});

Selectors for `usePuck`

Puck 0.19 introduces selectors for usePuck, letting you subscribe to the parts of the internal Puck API you need in order to avoid unnecessary re-renders. To use selectors, use the new createUsePuck helper, and pick which part of the API you want to listen to:

import { createUsePuck } from "@measured/puck";

const usePuck = createUsePuck();

const LeftSideBarButton = () => {
  // Will only re-render when closing or opening the left sidebar
  const isOpen = usePuck((s) => s.appState.ui.leftSideBarVisible);

  return <button>{isOpen ? "Close" : "Open"}</button>;
};

The original usePuck hook is still available and won’t be deprecated.

For a breakdown of how selectors compare with the original usePuck, check out the upgrade guide.

New hook: `useGetPuck()`

To make it possible to access the internal Puck API outside of the render lifecycle, we've added a new hook called useGetPuck().

import { useGetPuck } from "@measured/puck";

const SaveDataButton = () => {
  const getPuck = useGetPuck();

  const handleClick = useCallback(() => {
    // Access the latest appState only when the button gets clicked
    const { appState } = getPuck();

    saveData(appState.data);
  }, [getPuck]);

  return <button onClick={handleClick}>Save your page</button>;
};

useGetPuck returns a function that can be called to fetch the latest Puck API without triggering re-renders.

For a breakdown of how useGetPuck compares with the original usePuck, check out the upgrade guide.

Metadata API

This was a contribution made by: @jsjexpert

The metadata API lets you inject data into every component within your config, without relying on context.

const metadata = {
  pageId: "1234",
};

const config = {
  components: {
    Header: {
      render: ({ puck }) => <p>Page ID: {puck.metadata.pageId}</p>,
    },
  },
};

const Editor = () => {
  return <Puck config={config} data={{}} metadata={metadata} />;
};

Metadata can also be accessed within resolveData:

const metadata = {
  pageId: "1234",
};

const config = {
  components: {
    Header: {
      resolveData: async (data, { metadata }) => {
        return { props: { title: `Page ID: ${metadata.pageId}` } };
      },
      render: ({ title }) => {
        return <h1>{title}</h1>;
      },
    },
  },
};

const Editor = () => {
  return <Puck config={config} data={{}} metadata={metadata} />;
};

New recipe: `react-router`

This was a contribution made by: @matthewlynch

This version also includes a recipe for using Puck with the react-router framework, so you can scaffold new projects with everything pre-configured.

To use it, run create-puck-app and enter react-router when asked:

$ npx create-puck-app my-app

# Type "react-router"
? Which recipe would you like to use? react-router

Other changes

Improved performance

A big focus for this release was performance. Puck 0.19 drastically reduces the number of unnecessary re-renders, making the editor significantly faster and smoother, especially in larger projects.

To demonstrate this, we compared rendering times for common actions in 0.19 vs 0.18.3 using Puck with a test page containing 20 HeadingBlock components:

HeadingBlock: {
  fields: {
    title: { type: "text" },
  },
  render: ({ title }) => (
    <div style={{ padding: 64 }}>
      <h1>{title}</h1>
    </div>
  ),
},

These were the results:

Inserting a HeadingBlock was 82% faster in 0.19.
Replacing a HeadingBlock prop was 91% faster in 0.19.
Reordering a HeadingBlock was 79% faster in 0.19.
Deleting a HeadingBlock was 63% faster in 0.19.

Getters for item selectors

The internal Puck API (accessed with usePuck and useGetPuck) now includes a set of utilities to get component data from within the tree. These are useful when working with slots.

getItemBySelector gets an item’s ComponentData by selector.
getItemById gets an item’s ComponentData by component id.
getSelectorForId gets an item’s selector by component id.

getItemBySelector({
  index: 0,
  // The item is in the "children" slot field of the component with id "Flex-123"
  zone: "Flex-123:children",
});
// Returns: { type: "HeadingBlock", props: {...} }

getItemById("HeadingBlock-123");
// Returns: { type: "HeadingBlock", props: {...} }

getSelectorForId("HeadingBlock-123");
// Returns: { index: 0, zone: "Flex-123:children" }

Trigger event in resolveData

resolveData now receives a trigger parameter that tells you why it ran, whether it was because Puck was loaded ("load"), the component was dropped in the canvas (”insert”), props were updated ("replace"), or you forced it via resolveAllData ("force").

This gives you more control over how and when your data is resolved, so you can skip unnecessary fetches or run specific logic depending on the event.

const config = {
  components: {
    Header: {
      resolveData: async (data, params) => {
        // Resolve and add the title only when the Header is first dropped in
        if (params.trigger === "insert") {
          const resolvedTitle = await getTitle();

          return { props: { title: resolvedTitle } };
        }
        return data;
      },
      render: ({ title }) => {
        return <h1>{title}</h1>;
      },
    },
  },
};

Custom label icons for fields

This was a contribution made by: @DamianKocjan

You can now provide your own icons for field labels by passing a React node to the new labelIcon config parameter. If you're using the FieldLabel component directly, you can provide the icon via the icon prop.

import { TextCursor } from "lucide-react";

const config = {
  components: {
    Header: {
      fields: {
        title: {
          type: "text",
          labelIcon: <TextCursor size={16} />,
        },
      },
      render: ({ title }) => {
        return <h1>{title}</h1>;
      },
    },
  },
};

Field placeholders

This was a contribution made by: @DamianKocjan

Fields now support placeholders for text, textarea, and number fields.

To provide a placeholder, define the placeholder config parameter with the text you want to show.

const config = {
  components: {
    CompanyInfo: {
      fields: {
        name: {
          type: "text",
          placeholder: "Your company name here...",
        },
      },
      render: ({ name }) => {
        return <p>{name}</p>;
      },
    },
  },
};

Step size for number fields

This was a contribution made by: @shannonhochkins

You can now define a step value for number fields to control how much the value increases or decreases when using the input or keyboard arrow buttons. See step on MDN.

const config = {
  components: {
    EmptySpace: {
      fields: {
        height: {
          type: "number",
          step: 2,
        },
      },
      render: ({ height }) => {
        return <div style={{ height }} />;
      },
    },
  },
};

Hiding fields

It's now possible to hide fields from the UI by setting the visible field parameter to false.

const config = {
  components: {
    Header: {
      fields: {
        title: { type: "text" },
        hiddenField: {
          type: "text",
          visible: false,
        },
      },
      defaultProps: {
        title: "Title",
        hiddenField: "The field of this value is hidden",
      },
      render: ({ title, hiddenField }) => {
        return (
          <div>
            <span>{hiddenField}</span>
            <h1>{title}</h1>
          </div>
        );
      },
    },
  },
};

New `RootConfig` type

The new RootConfig type lets you type your root configuration with its expected props when using TypeScript. If you've broken up your config, this'll help you keep everything type-safe.

import { RootConfig } from "@measured/puck";

const rootConfig: RootConfig<{ title: string }> = {
  fields: {
    title: { type: "text" },
  },
  defaultProps: { title: "My Page" },
  root: ({ children, title }) => {
    return (
      <div>
        <h1>{title}</h1>
        {children}
      </div>
    );
  },
};

New `replaceRoot` action

The replaceRoot action is now available in the Puck API dispatcher, making it possible to update only the root data without using an expensive set action.

import { useGetPuck } from "@measured/puck";

const RootTitleSetter = () => {
  const getPuck = useGetPuck();

  const handleClick = useCallback(() => {
    // Get the dispatcher
    const { dispatch } = getPuck();

    // Dispatch the action to update the root
    dispatch({ action: "replaceRoot", rootData: { title: "New Title" } });
  }, [getPuck]);

  return <button onClick={dispatch}>Set Title</button>;
};

How to upgrade

Check out the upgrade guide for step-by-step instructions on upgrading to 0.19. It includes deprecated APIs, breaking changes, and common pitfalls.

Full changelog

See the full changelog for all changes via the GitHub release.

Contributors

[Boost]

Chris Villa — Thu, 27 Mar 2025 10:12:51 +0000

How to Build a React Page Builder: Puck and Tailwind v4.0

Fede Bonel Tozzi for Puck ・ Mar 26

#opensource #frontend #react #webdev

[Boost]

Chris Villa — Thu, 20 Mar 2025 10:59:51 +0000

Integrating a Page Builder with Contentful

Fede Bonel Tozzi for Puck ・ Mar 20

#opensource #cms #react #webdev

[Boost]

Chris Villa — Thu, 20 Feb 2025 13:55:37 +0000

Top 5 Drag-and-Drop Libraries for React

Fede Bonel Tozzi for Puck ・ Feb 20

#opensource #frontend #react #webdev

[Boost]

Chris Villa — Fri, 14 Feb 2025 18:08:37 +0000

Advanced Layouts with Puck 0.18: Harnessing Grid and Flex Containers

Fede Bonel Tozzi for Puck ・ Feb 14

#opensource #javascript #react #webdev

[Boost]

Chris Villa — Wed, 12 Feb 2025 10:03:58 +0000

Top 5 Page Builders for React

Fede Bonel Tozzi ・ Feb 8

#opensource #cms #react #webdev

Puck 0.18: New drag-and-drop engine

Chris Villa — Wed, 22 Jan 2025 12:47:25 +0000

Puck is the open-source visual editor for React, powering the next generation of page builders and no-code products. Give us a star on GitHub! ⭐️

Puck 0.18 launches a groundbreaking new drag-and-drop engine for page building with advanced CSS layouts.

With native support for CSS grid and flexbox, Puck 0.18 enables powerful new paradigms for creating design-in-browser experiences directly within your React application.

TLDR

New drag-and-drop engine: Multi-dimensional drag-and-drop across any CSS layout to create a sophisticated page building experience. Read the docs.
Dynamic DropZone height: DropZones now shrink to the height of their children, with a configurable height when empty.
Toggle interactive hotkey: Make your components interactive in Preview mode with the cmd+i hotkey.
Parent selector: A new action allows you to quickly select the component's parent directly from the action bar.
No more position: fixed: We've removed this pesky style from the default layout so it's easier to embed in your app.
New ActionBar.Label component: Create sections in your action bar with the new component.

Highlights

New drag-and-drop engine

Our flagship feature is a new drag-and-drop engine for Puck with full CSS grid & flexbox support to enable advanced layouts. We call these fluid layouts, and they are fully backwards compatible.

Thanks to @clauderic at dnd-kit for all the support in making this possible, and the Puck community for all the feedback! 🙏

Fluid layouts

To implement a fluid layout, add your display property of choice (e.g. display: flex) to your DropZone via the style or className props and off you go—Puck will gracefully handle drag-and-drop across all dimensions.

const config = {
  components: {
    Example: {
      render: () => (
        <DropZone
          zone="my-content"
          style={{ display: "flex" }} // Use flexbox in this DropZone
        />
      ),
    },
    Card: {
      render: ({ text }) => (
        <div>{text}</div>
      ),
    },
  },
};

See the Multi-column Layouts docs for the full documentation.

Remove wrapping elements

The new inline and dragRef APIs enable you to remove the wrapping element from Puck components entirely, which can be useful if you need to treat your component as a direct descendant of its parent (such as if you need to use CSS properties like flex-grow).

Here's an example implementing an advanced grid layout, where the children can specify their position using the grid-column and grid-row properties:

const config = {
  components: {
    Example: {
      render: () => (
        <DropZone
          zone="my-content"
          style={{ display: "grid", gridTemplateColumns: "1fr 1fr 1fr 1fr" }} // Use CSS grid in this DropZone
        />
      ),
    },
    Card: {
      inline: true, // Enable inline mode, removing the Puck wrapper
      render: ({ text, puck }) => (
        <div
          ref={puck.dragRef} // Let Puck know this element is draggable
          style={{ gridColumn: `span ${spanCol}`, gridRow: `span ${spanRow}` }} // Apply styles
        >
          {text}
        </div>
      ),
    },
  },
};

Dragging between nested DropZones

The new engine makes it possible to drag between nested DropZones, which resolves one of the longest standing limitations of Puck's drag-and-drop experience.

Dynamic DropZone height

DropZones now shrink to the height of their children so that the preview is a faithful representation of the final output, with a new configurable height when empty.

<DropZone
  zone="my-content"
  minEmptyHeight={256} // The DropZone will grow to 256px when empty
/>

The `<ActionBar.Label>` component

The new <ActionBar.Label> component enables you to to label areas within a custom ActionBar:

<ActionBar>
  <ActionBar.Label label="Label 1" />
  <ActionBar.Group>
    <ActionBar.Label label="Label 2" />
    <ActionBar.Action>★</ActionBar.Action>
  </ActionBar.Group>
</ActionBar>

Parent selector

A new action allows you to quickly select the component's parent directly from the action bar. Tap the arrow to the left of the component label to jump to the parent.

Toggle interactive hotkey

Make your components interactive directly within Preview mode with the cmd+i (or ctrl+i on Windows) hotkey.

This can be programatically set via the new previewMode parameter on the app state.

No more `position:fixed`

We've removed this pesky style from the default layout so it's easier to embed in your app. Not much to show here, but let's pour one out for position:fixed 🥂

Breaking changes

Drawer `direction` no longer has any effect

The direction prop on Drawer no longer has any effect. Instead, use it to wrap a div with your chosen display mode:

<Drawer>
  <div style={{ display: "flex" }}>
    <Drawer.Item name="Orange" />
  </div>
</Drawer>

DropZones are consistently wrapped in a div

Previously, DropZones were only wrapped in a div within the editor (<Puck>) environment, whereas the render (<Render>) environment used a fragment. This could result in unexpected rendering differences between environments.

Now, both environments use a div. If you were relying on the render environment behaving like a Fragment, you may need to adjust your styles. This can be done by applying your styles directly to the DropZone.

Before

<div style={{ display: "flex" }}>
  <DropZone zone="my-zone"> {/* Previously rendered as a fragment in <Render>, but div in <Puck> */}
    <div>Item 1</div>
    <div>Item 2</div>
  </DropZone>
</div>

After

<DropZone zone="my-zone" style={{ display: "flex" }}> {/* Now consistently renders as a div - apply your styles or class directly */}
  <div>Item 1</div>
  <div>Item 2</div>
</DropZone>

Deprecations

The index prop on Drawer.Item is no longer required and will be removed in a future version.
The droppableId prop on Drawer is no longer required and will be removed in a future version.

Full changelog

Features

add action to select parent component to ActionBar (7c910d5)
add ActionBar.Label component for adding labels to action bars (d2645fd)
add DropZone collisionAxis API for forcing collision direction (ba68732)
add meta+i hotkey and previewMode state to toggle interactivity (ec1eba5)
add wrapFields prop to control padding of fields in Puck.Fields (30f9a92)
control empty DropZone height with minEmptyHeight prop (96f8340)
deselect item on viewport change (e35585d)
forward the ref to the DropZone component (676aa1c)
introduce new drag-and-drop engine (6ebb3b8)
reduce DropZone to height of items unless empty (2b2595a)
remove position: fixed; from Puck layout (5deb774)
support inline Drawers, deprecating unnecessary props (f93b71e)

Bug Fixes

deselect item on delete (f27871b)
improve heading-analyzer reliability (ab6c018)
never render FieldLabel with padding or borders (a97b54f)
prevent propagation of custom ActionBar actions by default (14909bd)
prevent user pollution of ActionBar styles (e154cb7)
render DropZones the same in Puck and Render (d975aaf)
reset resolveFields lastFields param when changing component (7fead35)
select new item when dispatching duplicate action (e3d0025)
set root DropZone to 100% height (3d93f46)
stop actions from overflowing outside left of frame (c036b6d)
trigger iframe resize when closing devtools (2c0b782)

Contributors

Thanks to our contributors and sponsors for making this huge milestone possible. New contributors:

@1benw made their first contribution in https://github.com/measuredco/puck/pull/791

Like Puck? Give us a ⭐️ on GitHub.

Great write up on one of the most commonly asked Puck questions! Just use context!

Chris Villa — Tue, 14 Jan 2025 14:53:11 +0000

Managing application state in Puck

Fede Bonel Tozzi for Puck ・ Jan 14

#webdev #opensource #javascript #react

Awesome overview for using CSS variables to implement themes with Puck! 🎨

Chris Villa — Wed, 08 Jan 2025 18:30:32 +0000

Using CSS variables to create dynamic themes in Puck

Fede Bonel Tozzi for Puck ・ Jan 8

#webdev #tutorial #javascript #react

Puck 0.17 - React 19 and QOL improvements

Chris Villa — Wed, 18 Dec 2024 19:15:52 +0000

Puck is the open-source visual editor for React, empowering the next generation of page builders and no-code products. Give us a star on GitHub! ⭐️

Puck v0.17 adds support for React 19, improves various field APIs and squashes some bugs.

This is our final feature release of the year! We're delaying the new drag-and-drop engine release until January while we iron out the last few kinks. Happy holidays, and thanks for being a wonderful community 🎄

TLDR

React 19 support: We've made React 19 support official by adding it to the supported list of peer dependencies.
Next.js 15: Upgraded the next recipe to use Next 15.1 and React 19 by default.
New external field APIs: External fields now support react elements as rows, and a custom footer, enabling much more customization. Thanks to @camhammel for these improvements!
Duplicate array items: Added a new action to the array field so you can easily duplicate array items. Thank you @siarhei-zharnasek 🙏
resolveFields enhancement: You can now access the DropZone parent data when using the resolveFields API, enabling you to customize the fields based on the container's type or props.

Highlights

React 19 support

We've made React 19 support official by adding it to the supported list of peer dependencies. It turns out that earlier versions of Puck already play well with React 19, you don't need to upgrade Puck to use React 19 if you don't want to.

Next 15

The official next recipe now uses Next 15.1 and React 19 by default. If you're using the recipe and want to upgrade, make sure you also upgrade to React 19 as required by Next 15 when using the App Router. See the official Next.js upgrade guide for more info.

New external field APIs

The mapRow API now supports react elements, making it possible to add richer content to your external field table:

{
  type: "external",
  fetchList: async () => {
    return [
      { title: "Hello, world", imgUrl: "https://example.com/img.jpg" },
      { title: "Goodbye, world", imgUrl: "https://example.com/img.jpg" },
    ];
  },
  mapRow: (item) => ({ ...item, imgUrl: <img src={item.imgUrl} /> }),
}

And the new renderFooter API enables you to customise the footer of your external field modal.

{
  type: "external",
  fetchList: async () => {
    return [
      { title: "Hello, world" },
      { title: "Goodbye, world" },
    ];
  },
  renderFooter: ({ items }) => (
    <b>Custom footer with {items.length} results</b>
  ),
}

Duplicate array items

A new action in the array field allows you to easily duplicate array items.

Access parent data in resolveFields

The new parent param on the resolveFields API enables you to configure your fields based on the props of the parent item when using DropZones.

Here's an example that shows a field called flex when the parent component has a display prop of "flex":

const config = {
  components: {
    MyComponent: {
      resolveFields: (data, { fields, parent }) => {
        if (parent.props.display === "flex") {
          return {
            ...fields,
            flex: {
              type: "radio",
              options: [
                { label: "Grow", value: "grow" },
                { label: "Shrink", value: "shrink" },
              ],
            }
          }
        }

        return fields;
      },
      // ...
    },
  },
};

Full changelog

Features

add duplicate action to array field (229cbdd)
add renderFooter API to external field (ccec96e)
allow react elements in external field mapRow (2f781de)
enable resolveFields to access parent data (196227b)
list React 19 as supported peer dependency (85e8cc1)
track focused field in app state (91bc97a)
upgrade next recipe to v15.1 (8ef51c5)
use React 19 in next recipe (6b3d97f)

Bug Fixes

always run field resolvers when item change (159d819)
always update fields when resolveData runs (39dd619)
ensure radio fields are functional inside arrays (7736294)
prevent field name collision causing hook render mismatch (b51954a)
prevent flicker when using resolveData with arrays (1be9b88)
provide better error when usePuck used inappropriately (9991c07)
remove leading zeros in Number field (5ba9399)
respect original value type in radio and select fields (00ccd1d and 6e5864a)

New Contributors

@ruofee made their first contribution in https://github.com/measuredco/puck/pull/693
@DevOfManyThings made their first contribution in https://github.com/measuredco/puck/pull/698
@benlife5 made their first contribution in https://github.com/measuredco/puck/pull/695
@camhammel made their first contribution in https://github.com/measuredco/puck/pull/682
@siarhei-zharnasek made their first contribution in https://github.com/measuredco/puck/pull/676
@antonva made their first contribution in https://github.com/measuredco/puck/pull/707
@jswhisperer made their first contribution in https://github.com/measuredco/puck/pull/722

Full Changelog: https://github.com/measuredco/puck/compare/v0.16.2...v0.17.1

Puck 0.16: Permissions

Chris Villa — Tue, 17 Sep 2024 14:00:09 +0000

Puck is the open-source visual editor for React, empowering the next generation of page builders and no-code products. Give us a star on GitHub! ⭐️

We're celebrating 5,000 stars on GitHub! Thank you to our wonderful community!

Puck v0.16 is a big release, introducing the headline permissions API and — you guessed it — quality of life improvements. This one took a while to put together, and we appreciate your patience and support.

Permissions: Toggle Puck features like duplication, dragging, deletion through the new permissions and resolvePermissions APIs.
Action bar override: Create custom action bars using the actionBar override, or extend the default one using the new <ActionBar> component.
iframe style injection: Access the iframe document to inject styles directly, or make other changes, via the new iframe override. We also introduced the emotion-cache plugin for the common Emotion use-case.
History injection: Inject the undo/redo history via the a series of new APIs
React to actions: React to actions dispatched by Puck via the onAction callback.
Optional fields: Optional props are no longer required to define in fields, since they may be defined

Upgrade today or get started with:

npx create-puck-app@latest

Permissions

Permissions enable you to toggle core Puck functionality globally, on a per-component basis or dynamically. Huge thanks to @xaviemirmon for his efforts on this.

export function Editor() {
  return (
    <Puck
      permissions={{
        delete: false,
        duplicate: true
      }}
    />
  );
}

Action bar override

The new actionBar override enables you to create a custom action bar overlay, or extend the default one using the <ActionBar> component:

const overrides = {
  actionBar: ({ children }) => (
    <ActionBar label="Actions">
      {/* Render default actions */}
      <ActionBar.Group>{children}</ActionBar.Group>

      {/* Render new actions */}
      <ActionBar.Group>
        <ActionBar.Action onClick={() => console.log("Clicked!")}>
          ★
        </ActionBar.Action>
      </ActionBar.Group>
    </ActionBar>
  ),
};

iframe style injection

The iframe override enables you to access the iframe document, making it possible to inject styles into the head:

const overrides = {
  iframe: ({ children, document }) => {
    useEffect(() => {
      if (document) {
        document.body.setAttribute("style", "background: hotpink;");
      }
    }, [document]);

    return <>{children}</>;
  },
};

The new emotion-cache plugin uses this API to create an emotion cache inside the iframe, making Puck easy to use with any Emotion-based component library.

History injection

Use the new history injection APIs to provide your own undo/redo history via the initialHistory prop, or dynamically via the setHistories and setHistoryIndex functions from usePuck().history.

const historyState = {
  data: {
    root: {
      props: { title: "My History" },
    },
  },
};

export function Editor() {
  return (
    <Puck
      initialHistory={{
        histories: [{ state: historyState }],
        index: 0,
      }}
      // ...
    />
  );
}

React to actions

The onAction API enables you to react to Puck’s internal actions as they’re dispatched:

export function Editor() {
  return (
    <Puck
      onAction={(action, appState, prevAppState) => {
        if (action.type === "insert") {
          console.log("New component was inserted", appState);
        }
      }}
    />
  );
}

Breaking changes

`history.data` is now `history.state`

When using the usePuck history API, data is now renamed state.

`history.id` is now optional (TypeScript)

When using the usePuck history API id is now optional. Puck will always generate an id, but TypeScript may complain.

`lastData` is now returned as `null` instead of `{}` when empty in resolvers

When using the lastData option provided to resolveData or resolveFields functions, and there is no previous data, lastData will now be null instead of {}.

Full changelog

Features

add actionBar override for adding component controls (48ec0d7)
add automatic RSC export, replacing /rsc bundle (d21eba6)
add isDisabled prop to Drawer.Item (cad95b8)
add generic type to usePuck hook (01703a9)
add iframe override for style injection (7cac376)
add initialHistory prop to Puck (54b5a87)
add onAction API to track and react to state changes (c7007ac)
add permissions API (a43914d)
add plugin for injecting Emotion cache (f8a88b9)
add resolvePermissions API (f0655f0)
add waitForStyles option to iframe config (bc81d9c)
call resolveData when new item inserted (3298831)
don't mandate fields for optional props (5a219ef)
export ActionBar component for use in overrides (04fd6c5)
infer Data type from user config (50045bb)
make ID optional in History type (BREAKING CHANGE) (d917229)
provide ES Module build (ff9076b)
rename history.data to history.state (BREAKING CHANGE) (b09244c)
show spinner if iframe load takes over 500ms (cfecf54)
streamline usePuck history API (c8b2807)
upgrade "next" recipe to typescript@5.5.4 (60fe631)

Bug Fixes

add favicon to next recipe to prevent Puck 404 (2c52d27)
add missing readOnly state to External fields (bf1449d)
always record history on component insert (88c5ab6)
don't cache /edit route in Next recipe (94f16b2)
don't submit buttons if Puck used in form (f761e5f)
ensure demo types are satisfied with TypeScript@5 (958dc25)
export missing Plugin type (eb42734)
fix crash if component in data is missing from config (0daf478)
improve resiliency of iframe CSS for some frameworks, like Mantine (538cb05)
make Config and Data types more robust (6bcf555)
prevent infinite loop when using plugins with some frameworks (3870871)
prevent Tailwind from clashing with viewport zoom select (9151255)
remove body margin in remix recipe (0898b26)
resize viewport when changed via app state (14419ec)
resolve fields when switching between items of same type (a3518ca)
return lastData as null instead of empty object in resolvers (BREAKING CHANGE) (648eb92)
show warning if heading-analyzer styles aren't loaded (4e7110b)
use correct color in FieldLabel labels (b0469a1)

New Contributors

@mkilpatrick made their first contribution in https://github.com/measuredco/puck/pull/505
@nova4u made their first contribution in https://github.com/measuredco/puck/pull/538
@antonmalyavkin made their first contribution in https://github.com/measuredco/puck/pull/585

Full Changelog: https://github.com/measuredco/puck/compare/v0.15.0...v0.16.0

Puck 0.15: Dynamic fields

Chris Villa — Wed, 21 Aug 2024 08:31:11 +0000

Puck is the open-source visual editor for React, empowering the next generation of page builders and no-code products. Give us a star on GitHub! ⭐️

Puck v0.15 introduces powerful new field APIs and numerous quality-of-life features.

Dynamic fields: Use the resolveFields API to dynamically define your fields - great for showing fields conditionally or loading external APIs.
AutoField component: Build custom fields using Puck's own field component for a seamless UI.
Override the Publish button: Swap out the publish button without swapping out the entire header.
Context-aware components: Modify component behaviour based on whether it's inside <Puck> or <Render>.

Upgrade today or get started with:

npx create-puck-app@latest

Dynamic fields

Dynamic field resolution via the resolveFields API allows you to change the field configuration whenever the props change. You can use this to show and hide fields or even load data from an API.

Code example:

const config = {
  components: {
    MyComponent: {
      // ...
      resolveFields: (data) => ({
        myField: {
          type: "radio",
          options: [],  // Populate dynamically
        },
      }),
    },
  },
};

AutoField component

The AutoField component lets you render a Puck field based on a Field object. Use this when building custom fields that need to use Puck-style fields internally.

const CustomField = ({ onChange, value }) => (
  <AutoField field={{ type: "text" }} onChange={onChange} value={value} />
);

Override the Publish button

It's now possible to implement a custom Publish button without overriding the entire header by using the headerActions override.

<Puck
  overrides={{
    headerActions: ({ children }) => (
      <>
        {/* children will render default Publish button */}
        {children}
        {/* Or you can define your own */}
        <button>Click me</button>
      </>
    ),
  }}
/>;

This creates a breaking change for existing headerActions overrides, which will now need to render children to show the default Publish button.

Context-aware components

Components now receive the puck.isEditing prop. Use this to toggle functionality based on whether the component is being rendered in the <Puck> or <Render> context.

const config = {
  components: {
    MyComponent: {
      render: ({ puck }) => (
        <div style={{ background: puck.isEditing ? "hotpink" : "transparent" }}>
          Hello, world
        </div>
      ),
    },
  },
};

Breaking changes & deprecations

`headerActions` override must now render `{children}` (BREAKING CHANGE)

In order to support custom Publish buttons, the headerActions override will no longer render the default Publish button unless children are rendered.

<Puck
  overrides={{
    headerActions: ({ children }) => (
      <>
        {/* Render default Publish button */}
        {children}
      </>
    ),
  }}
/>;

Undocumented `editMode` API deprecated

The undocumented editMode prop is now deprecated in favor of puck.isEditing.

Full Changelog

Features

add AutoField component for using Puck fields inside custom fields (106028b)
add isEditing flag to puck object prop (13bb1bd)
add resolveFields API for dynamic fields (0a18bdb)
allow data prop to accept an empty object (aedd401)
bump next recipe to Next@14 (47a27ed)
enable override of publish button (breaking change) (480467a)
expose previous data to resolveData via lastData param (dd7051e)
replace history chevrons with undo/redo icons (91dff22)

Bug Fixes

align Drawer behaviour and docs with expectation (e2cd445)
animate loader in iframe (151a267)
don't inline link stylesheets for more predictable behaviour (c0a331d)
don't overflow external inputs inside arrays/objects (42ef582)
don't throw warning when user is correctly specifying root props (46aa8ff)
don't unintentionally use read-only styles in external fields (acaf727)
fix defaultProps for root (9a1cc7c)
infer correct value types in Custom fields (5c8c0e1)
position field loader relative to sidebar, not fields (2e8936e)
show external field modal when using custom interfaces (6e97a0e)
show field loader when using field overrides (8ccfa4c)
still load iframe if styles fail to load (3e56bc1)

See the GitHub release for the full changelog.

Community

We're grateful for the community's support and contributions. Join the conversation on GitHub and Discord.

Contributors

A huge thanks to all our existing and new contributors:

@goynang made their first contribution in https://github.com/measuredco/puck/pull/487

Forem: Chris Villa

Puck 0.19: Slots API & performance gains

What's new in Puck 0.19

Slots API

New function: walkTree

Selectors for usePuck

New hook: useGetPuck()

Metadata API

New recipe: react-router

Other changes

Improved performance

Getters for item selectors

Trigger event in resolveData

Custom label icons for fields

Field placeholders

Step size for number fields

Hiding fields

New RootConfig type

New replaceRoot action

How to upgrade

Full changelog

Contributors

[Boost]

How to Build a React Page Builder: Puck and Tailwind v4.0

Fede Bonel Tozzi for Puck ・ Mar 26

[Boost]

Integrating a Page Builder with Contentful

Fede Bonel Tozzi for Puck ・ Mar 20

[Boost]

Top 5 Drag-and-Drop Libraries for React

Fede Bonel Tozzi for Puck ・ Feb 20

[Boost]

Advanced Layouts with Puck 0.18: Harnessing Grid and Flex Containers

Fede Bonel Tozzi for Puck ・ Feb 14

[Boost]

Top 5 Page Builders for React

Fede Bonel Tozzi ・ Feb 8

Puck 0.18: New drag-and-drop engine

TLDR

Highlights

New drag-and-drop engine

Fluid layouts

Remove wrapping elements

Dragging between nested DropZones

Dynamic DropZone height

The <ActionBar.Label> component

Parent selector

Toggle interactive hotkey

No more position:fixed

Breaking changes

Drawer direction no longer has any effect

DropZones are consistently wrapped in a div

Deprecations

Full changelog

Features

Bug Fixes

Contributors

Great write up on one of the most commonly asked Puck questions! Just use context!

Managing application state in Puck

Fede Bonel Tozzi for Puck ・ Jan 14

Awesome overview for using CSS variables to implement themes with Puck! 🎨

Using CSS variables to create dynamic themes in Puck

Fede Bonel Tozzi for Puck ・ Jan 8

Puck 0.17 - React 19 and QOL improvements

TLDR

Highlights

React 19 support

Next 15

New external field APIs

Duplicate array items

Access parent data in resolveFields

Full changelog

Features

Bug Fixes

New Contributors

Puck 0.16: Permissions

Permissions

Action bar override

iframe style injection

History injection

New function: `walkTree`

Selectors for `usePuck`

New hook: `useGetPuck()`

New recipe: `react-router`

New `RootConfig` type

New `replaceRoot` action

The `<ActionBar.Label>` component

No more `position:fixed`

Drawer `direction` no longer has any effect

`history.data` is now `history.state`

`history.id` is now optional (TypeScript)

`lastData` is now returned as `null` instead of `{}` when empty in resolvers

`headerActions` override must now render `{children}` (BREAKING CHANGE)

Undocumented `editMode` API deprecated