DEV Community: Fede Bonel Tozzi

Puck 0.21: AI beta, rich text editing & new plugin rail

Fede Bonel Tozzi — Wed, 14 Jan 2026 13:07:00 +0000

Puck 0.21 introduces AI page generation, rich text editing, a new interface for Plugins, and more.

In this post, we’ll go over everything new in Puck 0.21 and how you can start using it:

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

If you’re upgrading from an earlier version, make sure to review the upgrade guide for any breaking changes and migration tips.

You can also find more in-depth documentation for each new feature in our docs.

What's new in Puck 0.21

Puck has moved

All packages have moved to the @puckeditor scope:

@puckeditor/core (from @measured/puck)
@puckeditor/field-contentful (from @measured/puck-field-contentful)
@puckeditor/plugin-emotion-cache (from @measured/puck-plugin-emotion-cache)
@puckeditor/plugin-heading-analyzer (from @measured/puck-plugin-heading-analyzer)

For step-by-step migration instructions, see the upgrade guide.

AI page generation

Puck 0.21 adds support for Puck AI, letting you generate pages from your existing Puck config.

Puck AI is now in open beta. Sign up now to get started.

Rich text editing

richtext is a new field type that provides a WYSIWYG editor with formatting options like bold, italic, alignment, and more.

To use it, add the richtext field to your component config:

const config = {
  components: {
    Article: {
      fields: {
        body: {
          type: "richtext",
        },
      },
      render: ({ body }) => <div>{body}</div>,
    },
  },
};

You can also enable inline editing in the canvas by setting contentEditable to true in the field config:

const config = {
  components: {
    Article: {
      fields: {
        body: {
          type: "richtext",
          contentEditable: true,
        },
      },
      render: ({ body }) => <div>{body}</div>,
    },
  },
};

The field is built with TipTap and is fully customizable. You can adjust the menus, formatting behavior, or introduce new TipTap extensions. See the docs for more details.

New UI: The Plugin Rail

After updating, you’ll see a new vertical navigation bar on the left-hand side of the editor. This bar is called the Plugin Rail.

Plugins can optionally appear as buttons in the rail and, when selected, render UI in the left sidebar.

By default, Puck includes three loaded plugins:

Blocks, which renders the component drawer
Outline, which renders the page structure outline
Fields, which renders the fields for the currently selected component

If you prefer the previous UI, you can opt out of the Plugin Rail by following the migration guide.

Add your own plugin UI

To render UI in the Plugin Rail, define a plugin object with the following parameters:

const myPlugin = {
  name: "author-info", // Globally unique identifier
  label: "Author", // Label shown in the rail
  icon: <User />, // Icon shown in the rail (lucide recommended)
  render: () => {
    // Component to render in the sidebar
    return (
      <div>
        <p>Page Author: John Doe</p>
        <p>Last updated: {new Date().toLocaleDateString()}</p>
      </div>
    );
  },
};

New mobile interface

On mobile, the sidebars are removed, and the editor now displays the Plugin Rail and plugin panel at the bottom of the screen.

New API: Change slot element with `as`

By default, Puck renders a div for every slot used in the page.

The new as prop lets you replace that with any HTML element or component you need:

const Main = (props) => {
  return <main {...props} />;
};

const config = {
  components: {
    Table: {
      content: { type: "slot" },
      render: ({ content: Content }) => {
        // Renders as <main>children</main>
        return <Content as={Main} />;
      },
    },
  },
};

New hotkeys: Delete and backspace

This was a contribution made by: SilasRopp1012

You can now press delete or backspace to remove a selected component from the page.

New component: `Puck.Layout`

The Puck.Layout component renders the default Puck UI.

This lets you use the Puck component as a provider of the internal Puck API without replacing the default editor layout.

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

const usePuck = createUsePuck();

const SelectedItemIndicator = () => {
  const selectedItem = usePuck((s) => s.selectedItem);

  return <p>{selectedItem?.type}</p>;
};

export function Editor() {
  return (
    <Puck>
      <SelectedItemIndicator />
      <Puck.Layout />
    </Puck>
  );
}

New field override: `custom`

This was a contribution made by shannonhochkins

The fieldTypes.custom override lets you customize how all custom fields are rendered. This is useful for wrapping them in a component or adding common logic or styles.

const overrides = {
  fieldTypes: {
    custom: (props) => {
      // Wrap all custom fields in a green border
      return (
        <div style={{ border: "1px green solid" }}>
          {props.field.render(props)}
        </div>
      );
    },
  },
};

Declaration merging for the `ComponentConfig` type

The ComponentConfig type can now be extended using declaration merging. This is useful for adding strictly typed custom properties to your component configs.

To use it, augment and use the interface ComponentConfigExtensions:

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

declare module "@measured/puck" {
  export interface ComponentConfigExtensions {
    test: boolean;
  }
}

const myComponentConfig: ComponentConfigExtensions = {
  test: true,
  // ...
};

Declaration merging for the `Metadata` type

You can now type Puck metadata using declaration merging. This is useful for working with strictly typed metadata at any level.

To use it, augment the following interfaces depending on where the metadata applies:

PuckMetadata – for metadata passed to the Puck or Render component.
ComponentMetadata – for metadata used in a ComponentConfig.
FieldMetadata – for metadata used in a field config.

import { Puck, ComponentConfig, Field } from "@measured/puck";

declare module "@measured/puck" {
  export interface PuckMetadata {
    id: string;
  }

  export interface ComponentMetadata {
    componentType: string;
  }

  export interface FieldMetadata {
    fieldType: string;
  }
}

const Editor = () => {
  return <Puck metadata={{ id: "123" }} />;
};

const ExampleComponent: ComponentConfig = {
  metadata: { componentType: "Example" },
  // ...
};

const fieldConfig: Field = {
  metadata: { fieldType: "text" },
  type: "text",
};

Declaration merging for Field types

All field types can now be extended using declaration merging. This is useful for adding strictly typed custom properties to your field configs, such as when using fieldTypes overrides.

To use it, augment the field type you need to extend:

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

declare module "@measured/puck" {
  export interface NumberField {
    isFloat: boolean;
  }
}

const myComponentConfig: NumberField = {
  type: "number",
  isFloat: true,
};

See the codebase for a list of all field types that can be augmented.

Other changes

New interaction: Deselect components on second click

A selected component can now be deselected by clicking it a second time.

New component: `ActionBar.Separator`

The ActionBar.Separator component lets you render a separator inside the ActionBar when using the actionBar override.
This is useful when you need visual separation between actions without grouping them with ActionBar.Group.

const overrides = {
  actionBar: () => {
    return (
      <ActionBar label="Actions">
        <ActionBar.Separator />
        <ActionBar.Action onClick={() => alert("Clicked!")}>
          Click me
        </ActionBar.Action>
      </ActionBar>
    );
  },
};

New `Puck` prop: `height`

You can now control the editor height by passing the height prop to the Puck component.

<Puck
  height="100%"
  // ...
/>

New `Puck` prop: `_experimentalFullScreenCanvas`

Setting _experimentalFullScreenCanvas to true on the Puck component removes the empty space around the editor canvas and displays the viewport switcher as a floating button.

<Puck
  _experimentalFullScreenCanvas
  // ...
/>

This prop is experimental and might change in the future.

New default viewport: Full-width

Puck now includes a Full-width default viewport that uses the full width of the canvas container without scaling the resolution.

Make viewports fill the container

Custom viewports can now fill the full width of the canvas container without scaling the resolution by setting the viewport width to 100%.

<Puck
  viewports={[
    {
      width: "100%",
      icon: <p>FullWidth</p>,
    },
  ]}
  // ...
/>

New `ActionBar.Action` prop: `disabled`

The ActionBar.Action component can now be disabled by setting the disabled prop to true.

const overrides = {
  actionBar: () => {
    return (
      <ActionBar label="Actions">
        <ActionBar.Action disabled onClick={() => alert("Clicked!")}>
          Click me
        </ActionBar.Action>
      </ActionBar>
    );
  },
};

New Puck API function: `resolveDataById`

The internal Puck API (accessed with usePuck or useGetPuck) now includes a utility to run a component’s resolveData by id. This is useful for triggering resolve data on the selected item.

<Puck
  {/* ... */}
  overrides={{
    headerActions: () => {
      const resolveDataById = usePuck((s) => s.resolveDataById);
      const selectedItem = usePuck((s) => s.selectedItem);

      return (
        <button onClick={() => resolveDataById(selectedItem.props.id)}>
          Refresh component
        </button>
      );
    },
  }}
/>

New Puck API function: `resolveDataBySelector`

The internal Puck API (accessed with usePuck or useGetPuck) now includes a utility to run a component’s resolveData for a given item selector. This is useful when inserting or updating components programmatically using the dispatcher.

<Puck
  {/* ... */}
  overrides={{
    headerActions: () => {
      const resolveDataBySelector = usePuck((s) => s.resolveDataBySelector);
      const itemSelector = usePuck((s) => s.ui.itemSelector);

      return (
        <button onClick={() => resolveDataBySelector(itemSelector)}>
          Refresh component
        </button>
      );
    },
  }}
/>

New Puck API function: `getParentById`

This was a contribution made by: eyueldk

The internal Puck API (accessed with usePuck or useGetPuck) now includes a utility to get an item’s parent ComponentData from the data tree. This is useful when working with slots.

const getParentById = usePuck((s) => s.getParentById);

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

Access `parent` data in `resolvePermissions`

resolvePermissions now receives the component’s parent ComponentData. This is useful for applying permissions conditionally based on where components are dropped.

const config = {
  Grid: {
    // ...
  },
  Item: {
    resolvePermissions: (data, params) => {
      if (params.parent.type === "Grid") {
        return { drag: false, delete: false };
      }

      return { drag: true, delete: true };
    },
    // ...
  },
};

Access `parent` data in `resolveData`

resolveData now receives the component’s parent ComponentData. This is useful for setting props conditionally based on where components are dropped.

const config = {
  Grid: {
    // ...
  },
  Item: {
    resolveData: (data, params) => {
      if (params.parent.type === "Grid") {
        return { props: { title: "Hello from Grid" } };
      }

      return data;
    },
    // ...
  },
};

Access `metadata` in `resolveFields`

This was a contribution made by: DamianKocjan

resolveFields now receives the component metadata. This is useful for defining fields conditionally based on data external to Puck.

const config = {
  Item: {
    fields: {
      // ...
    },
    resolveFields: (data, params) => {
      // Show an "id" field if the user is admin
      if (params.metadata.user.isAdmin) {
        return { ...params.fields, id: { type: "text" } };
      }

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

const Editor = () => (
  <Puck
    config={config}
    metadata={{ user: { isAdmin: true } }}
    // ...
  />
);

New trigger for `resolveData`: `move`

Previously, resolveData only ran when a component was first inserted, one of its fields changed, the Puck editor loaded, or resolveAllData was called.

Starting in Puck 0.21, resolveData also runs when a component is moved to a different slot.

To detect when this happens in the function, use the new "move" trigger parameter:

const config = {
  Grid: {
    // ...
  },
  Item: {
    resolveData: (data, params) => {
      // Reset the column span if the component moved to a different Grid
      if (params.trigger === "move" && params.parent.type === "Grid") {
        return { props: { columnSpan: 2 } };
      }

      return data;
    },
    // ...
  },
};

Use CSS units in Slot `minEmptyHeight` prop

Previously, the Slot render prop minEmptyHeight only supported pixel values. Starting in Puck 0.21.0, it now supports all CSS units.

const config = {
  PageContainer: {
    fields: { content: { type: "slot" } },
    render: ({ content: Content }) => {
      return <Content minEmptyHeight="50dvh" />;
    },
  },
};

Disable cache in `external` fields

This was a contribution made by: matthewlynch

By default, the external field caches and reuses the first output of the fetchList function in memory.

The new cache.enabled config parameter lets you disable this behavior so that fetchList always runs and retrieves the latest data when the component is selected in the canvas.

const config = {
  components: {
    Post: {
      fields: {
        data: {
          type: "external",
          cache: { enabled: false },
          fetchList: async () => {
            const now = new Date();

            return [{ title: "Post", createdAt: now.getTime() }];
          },
        },
      },
      // ...
    },
  },
};

Use functions for `defaultItemProps` in array fields

This was a contribution made by: LengYXin

defaultItemProps now accepts a function to set default props when a new item is added to the array field. This is useful for generating dynamic defaults based on the item’s insertion order.

const config = {
  components: {
    Example: {
      fields: {
        items: {
          type: "array",
          arrayFields: {
            title: { type: "text" },
            order: { type: "number" },
          },
          defaultItemProps: (index) => ({
            title: `Item ${index + 1}`,
            order: index + 1,
          }),
        },
      },
      // ...
    },
  },
};

Use JSX for `getItemSummary` in array fields

This was a contribution made by: DamianKocjan

getItemSummary in array fields now accepts any ReactNode as a return type.

This lets you use JSX for richer item summaries that include your own components.

const config = {
  components: {
    TodoList: {
      fields: {
        items: {
          type: "array",
          arrayFields: {
            title: {
              // ...
            },
            finished: {
              // ...
            },
          },
          getItemSummary: (item) => (
            <p>
              {item.title} –
              <span style={{ color: item.finished ? "green" : "red" }}>
                {item.finished ? "✓" : "x"}
              </span>
            </p>
          ),
        },
      },
      // ...
    },
  },
};

Use JSX for `getItemSummary` in external fields

This was a contribution made by DamianKocjan

getItemSummary in external fields now accepts any ReactNode as a return type.

This lets you use JSX for richer item summaries that include your own components.

const config = {
  components: {
    Books: {
      fields: {
        content: {
          type: "external",
          fetchList: async () => {
            return [{ title: "The Raven", author: "E. A. Poe" }];
          },
          getItemSummary: (item) => (
            <p>
              {item.title} –<span style={{ color: "gray" }}>{item.author}</span>
            </p>
          ),
        },
      },
      // ...
    },
  },
};

How to upgrade

To upgrade your Puck application to 0.21, follow the upgrade guide for step-by-step instructions. It covers deprecated APIs, breaking changes, and common pitfalls.

Full changelog

You can find the full changelog, including bug fixes and known issues, in the GitHub release.

Contributors

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

Fede Bonel Tozzi — Wed, 26 Mar 2025 13:56:12 +0000

If you’ve worked on content-heavy projects or low code tools before—especially alongside a headless CMS—you’ve probably faced this challenge: at some point, content teams want the ability to build and update pages without needing to go through a developer. That’s where website builders usually come in, but most of the ones out there are tied to a specific CMS or force you (and your built pages) into their ecosystem, making editor customization limited and migration hard, or expensive.

That’s exactly the problem Puck was built to solve. Puck is an open source, React-first visual editor that works in any project, with any CMS or back-end. This means no vendor lock-in or forced decisions on your stack, it’s just a simple package you install, import, and render in your app like any other React component.

And, because it’s just a component, you can use it alongside whatever you’re already using in your project—including Tailwind.

In this tutorial, I’ll walk you through how to:

🔨 Set up a page builder with Puck and Next.js
🔌 Integrate Tailwind v4.0 for interactive styling
📢 Create and publish web pages with it

Let’s dive in!

What Makes Puck Different

If this is the first time you’re hearing about Puck, there are a few reasons why you might consider using it. Puck is:

Open-source under an MIT license—You can use it in any project for free, personal or commercial.
Self-hosted—It’s just a React component you can embed directly into your app, so Puck lives wherever your app does.
Compatible with any headless CMS or backend—It renders any component you give it and provides external fields to connect to whatever content repository you’re using.
Customizable and overridable—You can use the editor as-is, replace parts of the UI, or build your own custom interface on top of it.
Extensible with plugins—You can add official plugins, community ones, or build your own to create reusable fields, behaviors, or integrations.

The core idea is simple: Puck gives you a visual editor to design and publish pages by dragging and dropping your React components. When a page is published, Puck outputs it as a JSON object. You can then pass that to the Render component to render that page wherever you want.

If you want to get a feel for how this setup works, you can try out the live demo yourself.

Here’s what that looks like in code:

// Editor.jsx
import { Puck } from "@puckeditor/core";
import "@puckeditor/core/puck.css";

const config = {
  // Define the components users can drag and drop in the editor
  components: {
    HeadingBlock: {
      // Define the editable fields for the component
      fields: {
        title: {
          type: "text",
        },
      },
      // Render the component with the field values
      render: ({ title }) => {
        return <h1>{title}</h1>;
      },
    },
  },
};

// Provide an initial page to load into the editor (empty for new pages)
const initialData = {};

// Save the page when the user clicks on Publish
const save = (data) => {
  console.log(data); // Replace this with a call to your backend
};

// Render the Puck editor
export function Editor() {
  return <Puck config={config} data={initialData} onPublish={save} />;
}

And to render a saved page:

// Page.jsx
import { Render } from "@puckeditor/core";

export function Page() {
  const data = {}; // Load this from your database

  return <Render config={config} data={data} />;
}

Now that you know what Puck is, why it’s worth your while, and how it works, let’s actually start building the page builder!

Step 1: Add Puck

Installing Puck

First up, let’s install Puck. If you’re adding it to an existing project, you can install it directly via npm:

npm install @puckeditor/core

If you’re starting from scratch, you can also use one of the Puck recipes to spin up a new project:

npx create-puck-app my-app

This will scaffold a new project called my-app, feel free to swap that name for whatever fits your project.

After running that command, you’ll be prompted to choose a recipe. Type next for the Next.js recipe, or remix if you prefer Remix.

For this guide, I’m using the Next.js recipe, but if you’re adding Puck to an existing project, or using the Remix recipe, the next steps should still apply. You might just need to adjust the file paths to match your project folder structure.

Running Puck

With Puck installed, let’s get the app running. If you used the recipe, you can start your development server using the following commands:

# Navigate into the new project folder
cd my-app

# Start the development server
npm run dev

That’ll spin up the app at http://localhost:3000. When you first open it, you’ll see a message prompting you to navigate to the editor to edit that specific page. To do that, just head over to: http://localhost:3000/edit

You should now see the Puck editor, with a single HeadingBlock component already in the canvas.

If you click on the HeadingBlock in the canvas, modify its title field, and hit Publish in the top-right corner, you’ll update your homepage at http://localhost:3000 instantly.

You can also add /edit at the end of any page URL to create or edit that page visually—whether it already exists or not. This works thanks to the Next.js catch-all route (app/[...puckPath]) that comes pre-configured with the Puck Next.js recipe.

⚠️ Heads up: By default, the Next.js recipe saves page data to your file system and leaves the editor open to anyone. That’s fine for local development, but if you’re deploying this to production, you’ll want to check the recipe docs for tips on authorizing your API routes and saving pages to a real database

Adding Typescript to Puck

Before we start adding custom components, let’s take a quick look at the configuration object that comes with the recipe in ./puck.config.tsx to understand how Puck gets integrated with TypeScript.

At the top of the file, you'll see a Props type definition. This tells Puck’s Config type what props each of your draggable components expects. In this case, we only have a single component—HeadingBlock—and it just expects a title string.

// puck.config.tsx
import type { Config } from "@puckeditor/core";

type Props = {
  HeadingBlock: { title: string };
};

Next is the actual Puck config object. The only difference with the previous JavaScript setup here is that we’re typing it with Config to let TypeScript know which components it expects and which fields each one of those components should define. It also uses defaultProps, to define a default value for the title field.

export const config: Config<Props> = {
  components: {
    HeadingBlock: {
      fields: {
        title: { type: "text" },
      },
      defaultProps: {
        title: "Heading",
      },
      render: ({ title }) => (
        <div style={{ padding: 64 }}>
          <h1>{title}</h1>
        </div>
      ),
    },
  },
};

export default config;

And that’s the basic setup with TypeScript!

Keep in mind that, as your editor grows, you’ll definitely want to pull these nested component configuration objects to their own files, when you do that, you can type them by using the ComponentConfig type Puck exposes with the props you expect for the component.

Adding Components to Puck

Now that we’ve got Puck setup and ready, it’s time to make things more interesting. Let’s add a couple of new components:

Card: to present information about a particular topic
Grid: to display a list of components in a grid, using CSS grid

For this tutorial, the Grid itself won’t need any props—it’s just going to be a layout container—but each Card will allow users to input the title and description of the topic it's introducing, as well as the amount of padding it should have around its content.

Here’s how to set this up:

Step 1: Add the new Grid and Card components to the Props type

// ./puck.config.tsx

type Props = {
  HeadingBlock: { title: string };
  Grid: {}; // No props needed for the grid itself
  Card: {
    title: string;
    description: string;
      padding: number;
  };
};

//... existing setup

Step 2: Add the Grid component to the config object

To do this, we’ll use the DropZone component. This component allows you to nest components within other components, which is useful for creating multi-column layouts using CSS Grid or Flexbox.

// ./puck.config.tsx
import { Config, DropZone } from "@puckeditor/core";

export const config: Config<Props> = {
  components: {
    //... existing config

    Grid: {
      render: () => {
        // Render a Grid DropZone where users are able to drag and drop components
        return (
          <DropZone
            zone="my-grid"
            style={{
              display: "grid",
              gridTemplateColumns: "repeat(3, minmax(0, 1fr))",
              gap: "16px",
            }}
          />
        );
      },
    },
  },
};

Step 3: Add the Card component to the config object

// ./puck.config.tsx

import { Config, DropZone } from "@puckeditor/core";

export const config: Config<Props> = {
  components: {
    //... existing config

    Card: {
      // Add the fields for the title, description and padding
      fields: {
        title: { type: "text" },
        description: { type: "textarea" },
        padding: { type: "number", min: 4, max: 64 },
      },
      // Add default values for each field
      defaultProps: {
        title: "Topic Title",
        description: "Topic description...",
        padding: 16,
      },
      render: ({ title, description, padding }) => {
        // Render the card using the values from its fields
        return (
          <article style={{ padding }}>
            <h2>{title}</h2>
            <p>{description}</p>
          </article>
        );
      },
    },
  },
};

That’s it! If you head back to http://localhost:3000/edit, you’ll now see Grid and Card in your component list. Go ahead and drop a Grid into the page and add a few Cards inside it, adjusting their titles, descriptions, and padding to see how it all comes together.

Step 2: Integrate Tailwind

At this point, we’ve got a working page builder—components can be dragged in, props can be edited, and pages can be published. But visually, things are still pretty basic. Let’s fix that by adding Tailwind to the mix.

Installing Tailwind

Adding Tailwind to a project with Puck is the same as adding it to any React app. Since this tutorial uses Next.js, I’ll walk you through that setup, but if you’re using a different meta framework, you can follow the official Tailwind instructions for your particular stack.

Step 1: Install Tailwind and its dependencies

npm install tailwindcss @tailwindcss/postcss postcss

Step 2: Create a ./postcss.config.mjs file in the root of your project and add the Tailwind plugin to it

// ./postcss.config.mjs

const tailwindConfig = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

export default tailwindConfig;

Step 3: Import Tailwind in ./app/styles.css

/** ./app/styles.css **/

@import "tailwindcss";

And with that, Tailwind is now part of your project. Next, we’ll wire it up to your Puck components so you can start using it inside the editor.

Migrating to Tailwind

Once Tailwind is installed, you can start swapping out the existing styles in your Puck components for Tailwind’s utility classes. Let’s do a quick cleanup by migrating the static inline styles we were using in HeadingBlock and Grid.

To do that, open ./puck.config.tsx and make the following changes:

// ./puck.config.tsx

export const config: Config<Props> = {
  components: {
    HeadingBlock: {
      //... existing configuration

      render: ({ title }) => (
        // Replace the inline styles to make the text bigger and bold
        <div className="text-4xl font-bold p-8">
          <h1>{title}</h1>
        </div>
      ),
    },
    Grid: {
      render: () => {
        return (
          // Replace the inline styles with Tailwind's equivalent
          <DropZone zone="my-grid" className="grid grid-cols-3 gap-4 p-4" />
        );
      },
    },

    //... existing card configuration
  },
};

Once that’s done, you can navigate back to the editor and check that everything is styled as expected, if this doesn’t seem to be working you might need to reset your development server and invalidate your browser cache.

Applying Tailwind Dynamically

With Puck, you often want to change the appearance of a component based on the value of a field controlled by the user, just like we did earlier with the card padding.

Doing this with Tailwind works great in most cases, but there’s one important thing to keep in mind: Tailwind doesn’t generate styles at runtime. Instead, it scans your code at build time, finds any utility classes you’re using (like text-center or bg-red-500), and then includes only those in your final CSS bundle. Tailwind’s docs explain this in more detail.

That means if you try to do something like this using a field value:

className={`grid-cols-${columns}`}

…it won’t work unless the class for every possible value of columns is already present somewhere in your source code. That’s because Tailwind won’t recognize the dynamic class when it builds your CSS.

Luckily, there are a few ways to work around this depending on how dynamic you want your styling to be. Let’s go through the options so you can pick the one that fits your setup best.

Option 1: Predefined static classes and inline styling (simplest)

If all you want to do is give users a set of predefined styles they can pick from, for example through a select or radio field, this is the simplest way to integrate Tailwind. To achieve this, hard-code the fixed list of classes your components can use, the same way you would in any other project. This would make it so all the classes exist at build time, making it the safest and most performant option.

Any other fully dynamic values the user controls directly—like the padding around the Card’s content—can still be passed using inline styling.

To demonstrate this, let’s add a variant field to the Card component so users can choose between an “outlined” or a “floating” card. The padding around the card content will stay as inline styles, so users can still enter any values they want.

Step 1: Add the variant prop in the Card type definition

// ./puck.config.tsx

type Props = {
  //... existing components

  Card: {
    //... existing props

    variant?: string;
  };
};

Step 2: Add a select field for the Card variants with their corresponding Tailwind classes as values

// ./puck.config.tsx

export const config: Config<Props> = {
  components: {
    //... existing components

    Card: {
      //... existing configuration

      fields: {
        //... existing fields

        variant: {
          type: "select",
          options: [
            { value: "shadow-md", label: "Floating" },
            { value: "border rounded-md", label: "Outlined" },
          ],
        },
      },
    },
  },
};

Step 3: Add the variant prop to the Card class names

// ./puck.config.tsx

export const config: Config<Props> = {
  components: {
    //... existing components

    Card: {
      //... existing configuration

      render: ({ title, description, padding, variant }) => {      
        return (
          <article
            style={{ padding }}

            // Pass in the variant prop here
            className={variant}
          >
            <h2 className="text-xl font-bold">{title}</h2>
            <p>{description}</p>
          </article>
        );
      },
    },
  },
};

If you now navigate to the editor and drag and drop a Card, you’ll be able to switch between an outlined Card or a floating one by using the new variant field.

You can repeat this setup with any other component you want. The key is always making sure the full class names exist somewhere in your code so Tailwind can pick them up. Anything that’s truly dynamic—like widths, heights, or grid spans—can stay inline.

The only downside to this approach is that you won’t be able to use selectors, design tokens, or target states with the fully dynamic inline values.

Option 2: Predefined dynamic classes (longer boilerplate)

The previous setup works great for static class names, but it doesn’t solve the problem when you need to generate classes dynamically, which might be a requirement for doing things like selecting a specific color for a background like this:

const className = `bg-${colorOption}`

In Tailwind v3, you could achieve this by safelisting the class names you wanted in the final CSS bundle so that they were always included. You could even use regular expressions to safelist whole sets of possible class variants in one line, making it easier to cover dynamic class names.

In Tailwind v4.0, however, doing that is no longer possible. To do this now, you need to safelist all the exact class names you’ll be generating dynamically in a .txt file.

Here’s how you’d do that for adding background colors to the Card component in our setup:

Step 1: Create a ./safelist.txt file that contains all the Tailwind classes you need to generate dynamically

bg-inherit
bg-red-300
bg-yellow-100

...any other class names you need

Step 2: Import this file into your main stylesheet using @source so Tailwind knows to include these classes in the final build

/* ./app/styles.css */
@source "../safelist.txt";

Step 3: Add a background field to the Card component, so users can choose a background color in the editor

// ./puck.config.tsx

type Props = {
  //... existing components

  Card: {
    //... existing props

    background?: string;
  };
};

export const config: Config<Props> = {
  components: {
    //... existing components

    Card: {
      //... existing configuration

      fields: {
        //... existing fields

        background: {
          type: "select",
          options: [
            { value: "inherit", label: "Inherit" },
            { value: "yellow-100", label: "Yellow" },
            { value: "red-300", label: "Red" },
          ],
        },
      },

      //... default props configuration

      render: ({ title, description, padding, variant, background }) => {
        return (
          <article
            style={{ padding }}

            // Add the background class dynamically
            className={`${variant} bg-${background}`}
          >
            <h2 className="text-xl font-bold">{title}</h2>
            <p>{description}</p>
          </article>
        );
      },
    },
  },
};

If you now refresh your editor, drag and drop a card, and select a red or yellow background, you should see your card changing colors.

The key of this approach is making sure all your dynamic class names always resolve to those defined inside the safelist.txt file. Here I showed you how to do it manually, but you could write scripts to generate some repetitive ones, like a range of paddings and margins, automatically.

The downside of this approach is that every new dynamic class must be manually added, slowing down updates and increasing the risk of missing a class, which could lead to styling bugs.

Bonus Option: Import all classes by using the CDN (Heaviest)

If you want to give users full control over things like padding, margin, colors, and fonts—purely using dynamic Tailwind classes—the previous option will quickly become unmanageable. You’d need to add hundreds of class names to your safelist just to support a handful of design fields.

The only real workaround is to make every Tailwind class available at runtime, and the way to do that is by loading Tailwind via its CDN. With the CDN, Tailwind doesn’t need to scan your files at build time—it ships all the styles up front and generates them on the fly in the browser. That means you can do things like "p-${padding}" freely, without worrying about safelists or build time scans.

The main disadvantage of this approach is that you’re importing all of Tailwind, all the time. Which adds around 220 KB to your pages, just for styling, most of which you’ll probably never use. It also makes your styling runtime-dependent, which means worse performance, especially on slower connections or less powerful devices.

That’s why the Tailwind team doesn’t recommend this setup, and why I’m not going to cover it in depth here.

If you still want to go for it, you can follow the official instructions here. Just be sure to remove Tailwind as an npm dependency, since you won’t be using it at build time anymore.

Use this approach carefully, it gives you complete freedom, but you’ll pay for it in performance.

Wrapping up

This tutorial walked through how to combine Tailwind with Puck to build a flexible, component-based page builder. We covered different ways to handle component styling—from simple predefined classes and inline styling to fully dynamic values—so you can pick the right balance between flexibility, maintainability, and performance.

Hopefully, this guide not only helped you set up Tailwind in Puck but also sparked some ideas for building your own visual editors—whether that’s for website builders, image editors, PDF generators, or something else entirely. The best thing about Puck is that it’s not just a page builder—it’s a component-based editor, so what your components represent and what you build with it is completely up to you.

If you’re exploring this setup, working on something similar, or tackling something completely different, I’d love to chat and answer any questions you might have:

👾 Join the conversation on Discord

🐦 Follow along for updates and sneak peeks on X and Bluesky

⭐ Found this useful? Support Puck by giving us a star on GitHub—it really helps!

Integrating a Page Builder with Contentful

Fede Bonel Tozzi — Thu, 20 Mar 2025 10:33:03 +0000

Puck is the open-source visual editor for React that you can embed in any application to create the next generation of page builders and no-code products. Give us a star on GitHub! ⭐️

Headless CMS platforms like Contentful have changed how we think about content management. Instead of locking you into a specific frontend, like traditional CMSs do, they let you store structured content and deliver it anywhere—websites, mobile apps, even IoT devices.

But that flexibility comes with a trade-off: you don’t really know how your content will be presented. Unlike traditional CMSs that include WYSIWYG editors, headless CMSs require developers to build the frontend experience from scratch. This means content teams often need to rely on engineers just to tweak layouts, adjust styling, or add new sections to pages.

What’s the solution to this? A dedicated page builder. A good page builder gives content teams the freedom to structure pages visually, while still keeping the content store separate, ensuring that every component in the system remains dynamic and modular. There are plenty of proprietary ones out there, but if you want full control over your tech stack, a CMS-agnostic page builder is the way to go.

That’s where Puck comes in. Puck is a flexible, open-source page builder that you can embed directly into your React app. It’s completely unopinionated about how you store and retrieve content, making it compatible with virtually any backend (not just CMSs), including Contentful. This makes it a great fit if you want a dynamic editor that doesn’t tie you to a single platform.

In this tutorial, I’ll show you how to integrate Puck with Contentful to bridge the gap between reusable structured content and a user-friendly page-building experience. By the end, you’ll learn how to:

Set up a React project with Puck
Connect it to Contentful to import your content (blog posts)
Build and publish pages directly within Puck so they can be rendered in your application

By the time we're done, you’ll have a fully functional visual editor + headless CMS setup where users can write blog posts and build and edit pages dynamically—without writing a single line of code:

Before we get started, I’ll assume you have a basic understanding of Contentful. If you're new here, no worries—you’re welcome to follow along! However, I’d recommend checking out the Contentful developer portal first to get familiar with the basics.

Set up Contentful
Add Puck
Connect Puck with Contentful
Edit and Publish your Pages
Taking your Page Builder Further

📝 1. Set up Contentful

To begin, we need to define our content structure in Contentful. Since this tutorial focuses on integrating a page builder rather than setting up Contentful from scratch, I’ll keep this section brief. If you're new to Contentful, I recommend checking out their official getting started guide to get familiar with creating spaces, content types, and obtaining your API keys.

For this simple blog app, you only need to define a single content type named Blog, which represents the collection of blog posts you’ll publish and manage in your app. Here are the fields you should add to it:

Title: A required text field for the blog post title
Body: A required rich text field for the blog content

Once you create that content type you’ll be able to navigate to the “Content” section of your Contentful space to create new Blog posts based on this model:

👩‍💻 2. Add Puck

After setting up Contentful, we can now set up the web application to build and render pages with our content. To do this, we’ll use Puck both for page building and rendering.

If you're completely new to Puck and want a broader introduction before diving in, check out our Getting Started guide.

Installing Puck

If you’re adding Puck to an existing project, you can install it with npm:

npm install @puckeditor/core

Or, if you’d rather start fresh, you can use one of the Puck recipes to quickly set up a new project:

npx create-puck-app my-blog

This will create a new Puck project named my-blog (feel free to rename it). After running the command, you’ll be prompted to choose a recipe—type next for the Next.js recipe or remix for the Remix recipe.

For this guide, I’ll assume you’ve used the generator and chosen the Next.js recipe, however if you’re integrating Puck into an existing project, the next steps should still apply. Puck works with any React application, so you might just need to tweak file names and folder structures based on your preferred setup.

Running Puck

Once Puck is installed, you can start your development server. To do this run the following commands:

# Navigate to your new project
cd my-blog

# Run the application
npm run dev

This will start a local development server on http://localhost:3000. If you navigate to it, you’ll be shown a sample message that will prompt you to navigate to the editor. To access the Puck editor, head over to: http://localhost:3000/edit

You should now see the Puck editor, rendering a single component: HeadingBlock.

Click on the HeadingBlock in the canvas, modify it’s content to whatever you want and hit Publish in the top-right corner to update your homepage at http://localhost:3000 instantly.

You can also add /edit at the end of any page URL to edit that page visually—whether it already exists or not. This works thanks to the Next.js catch-all route (app/[...puckPath]) that comes pre-configured with the Puck Next.js recipe.

⚠️ Important: By default, Puck’s Next.js recipe saves your page data in the file system and makes all pages editable by anyone. If you plan to deploy this app to production, be sure to check out the recipe documentation for best practices on securing API routes and storing page data in a real database.

Great, now we have our client app and our CMS ready! Next, we'll connect Contentful to Puck so we can create pages using the content we created in step one.

🔗 3. Connect Puck with Contentful

For this step, we'll use the @puckeditor/field-contentful package, which provides a Puck field that allows you to select Contentful entries directly inside the editor. This package is a convenience wrapper around Puck's external field type, handling the Contentful API integration. You can see the source code here.

We’ll also install Contentful’s rich-text-react-renderer package to properly render Contentful’s rich text field data with HTML.

1. Install Dependencies

Start by installing the dependencies.

npm i @puckeditor/field-contentful @contentful/rich-text-react-renderer

2. Define an Article Component

Next, add an Article component to allow users to select and display a blog post entry in the pages they’re building. Open /puck.config.tsx, and modify the Puck props type definition and config to define the new component.

//... existing setup

type Props = {
  //... existing props

  Article: {
      // TODO: add the Article props
  };
};

export const config: Config<Props> = {
  components: {
    //... existing setup

    Article: {
      //... TODO: add the component config
    },
  },
};

3. Add the Field to Select Contentful Entries

Inside the Article component definition, use the createFieldContentful function from @puckeditor/field-contentful to create a field that lets users select a blog post from Contentful. Define this field under a data prop in the Article component's fields.

import createFieldContentful, { Entry } from "@puckeditor/field-contentful";

// Define the expected props for the Article component
type ArticleProps = {
  // Expect contentful entries as article data
  data?: Entry<{ title: string; body: any }>;
};

type Props = {
  //... existing props

  // Replace the empty object definition with the actual type
  Article: ArticleProps;
};

export const config: Config<Props> = {
  components: {
    //... existing setup

    Article: {
      fields: {
        data: createFieldContentful<ArticleProps["data"]>("blog", {
          space: "YOUR-SPACE-ID",
          accessToken: "YOUR-ACCESS-TOKEN",
        }),
      },
    },
  },
};

🔹 Important: Replace YOUR-SPACE-ID and YOUR-ACCESS-TOKEN with your actual Contentful space ID and API token. Storing these in environment variables (.env) is recommended.

4. Render the Selected Blog Post

Once a blog post is selected via the data field, the data prop will be provided to the component’s render function for rendering. Modify the Article’s render function to show the contents of the blog post in the page.

import { documentToReactComponents } from "@contentful/rich-text-react-renderer";

//... existing setup

export const config: Config<Props> = {
  components: {
    //... existing setup

    Article: {
      //... existing field setup

      render: ({ data }) => {
        // If the user selected a blog entry,
        // render it
        return data ? (
          <div style={{
            fontFamily: "Arial, sans-serif",
            padding: 32,
          }}>
            <h1>{data.fields.title}</h1>
            <hr />
            {documentToReactComponents(data.fields.body)}
          </div>
        ) : (
          <h1>No selected content</h1>
        );
      },
    },
  },
};

Now that everything is set up, navigate to http://localhost:3000/edit and try the following:

Drag and drop an Article component onto the editor
Click the component and select a blog post from Contentful
The title and body of the selected blog post should now appear in the editor preview

Reusing Components

Let's extend the Article component to support different types of content. To demonstrate this, we'll create a separate About content type, and generalize the Article component so that it works with multiple types.

1. Create the About content type

In Contentful, create an About content type with the same fields as the Blog type:

Title: a required text field for the section title
Body: a required rich text field for the section content

💡 Pro Tip: While you can handle different content type structures using the resolveData API, keeping consistent field names across related content types—like in this example—makes components in Puck instantly reusable. Without any extra implementation, new content types will work automatically with your existing components.

2. Define your own Contentful Client

Previously, the @puckeditor/field-contentful package created the Contentful client internally for us. However, since we now need to retrieve the available content types in our space dynamically, we’ll need to create the client manually and use it for fetching them.

To do this, modify your createFieldContentful setup to explicitly create the Contentful client:

import createFieldContentful, {
  Entry,
  createClient, // Import the client builder
} from "@puckeditor/field-contentful";

// Explicitly create the Contentful client
const contentfulClient = createClient({
  space: "YOUR-SPACE-ID",
  accessToken: "YOUR-ACCESS-TOKEN-HERE",
});

export const config: Config<Props> = {
  components: {
    //... existing setup

    Article: {
      fields: {
        data: createFieldContentful<ArticleProps["data"]>("blog", {
            // Pass the previously created client
          client: contentfulClient,
        }),
      },
    },
  },
};

3. Move the Contentful Field Definition Inside resolveFields

Next, you'll want to make the fields dynamic, so that the content type passed to the Contentful field definition can be changed based on the value of another field.

To do this, migrate your field definition to the resolveFields API:

// Import the Fields type
import type { Config, Fields } from "@puckeditor/core";

export const config: Config<Props> = {
  components: {
    //... existing setup

    Article: {
      resolveFields: async (data, params) => {
        let newFields: Fields<ArticleProps> = {
            data: createFieldContentful<ArticleProps["data"]>("blog", {
              client: contentfulClient,
            }),
        };

        return newFields;
      },

      //... existing setup
    },
  },
};

4. Let Users Select a Content Type

Now, add a contentType prop to the Article component config, and configure it with a select field that's populated with a list of all the available content types from Contentful.

When the user changes the value of the contentType select field, pass it to the createFieldContentful call in resolveFields, so the data field now points to a different content type.

//... existing setup

type ArticleProps = {
  data?: Entry<{ title: string; body: any }>;

  // Add a prop for selecting a content type
  contentType: string;
};

//... existing setup

export const config: Config<Props> = {
  components: {
    Article: {
      resolveFields: async (data, params) => {

        // Fetch all available content types from Contentful
        const types = await contentfulClient.getContentTypes();

        let newFields: Fields<ArticleProps> = {
          // Create a dropdown field for selecting a content type
          contentType: {
            type: "select",
            options: [
              { label: "Select a content type", value: "" },
              ...types.items.map((type) => ({
                label: type.name,
                value: type.sys.id,
              })),
            ],
          },
        };

        // If a content type is selected, add an entry picker for it
        if (data.props.contentType) {
          newFields.data = createFieldContentful<ArticleProps["data"]>(
            data.props.contentType,
            {
              client: contentfulClient,
            }
          );
        }

        return newFields;
      },

      //... existing render function
    },
  },
};

Finally, navigate to the editor in the browser, drag and drop an article, choose a content type, and then select the actual entry of that content type you want to render:

📰 4. Edit and Publish your Pages

Now that everything is set up, you can start building and publishing blog posts directly from your app.

For example, if you want to add a new post about, say, the Top 5 Drag and Drop Tools for React, all you need to do is:

Create a new blog entry in Contentful for it
Navigate to http://localhost:3000/top-5-drag-and-drop-libraries-for-react/edit
Drag and drop an Article component onto the page
Select the “Blog” content type and pick your new post from the Contentful entries
Preview the page, tweak the layout if needed, and hit "Publish" in the top-right corner

That’s it! Your new page is now live and accessible at http://localhost:3000/top-5-drag-and-drop-libraries-for-react 🎉

Taking your Page Builder Further

If you want to expand this setup, here are a few ideas to take it to the next level:

Add a styling library – For larger editors, using a styling library like Tailwind or Emotion can streamline your workflow, reduce boilerplate, and help maintain a consistent design system. Puck even has an Emotion plugin that makes integration seamless if you’re using that library
Build dynamic blog post listing – While this tutorial covered rendering a single blog post page, you’ll probably want to let users browse all posts. For that, you can apply the same reusability concepts from this tutorial to create a ContentList component that dynamically lists entries from any content type
Enable content authoring in Puck – Instead of switching between Puck and Contentful, you could integrate Contentful’s Content Management API with Puck’s resolveData function to allow users to author content directly inside the page builder
Republish the page if the content changes – One limitation of the current setup is that, if you change your content on Contentful, that won’t be reflected on your published Pages. This is because, by default, Puck fetches and copies the content when you first select it in the editor. To fix this, you can use the resolveData function in the Article component to fetch the latest content from Contentful whenever the component renders. Check out our guide on how to implement this here

🔚 Wrapping up

In this tutorial, I walked you through a simple way to integrate Puck with Contentful, but this is just one of many possible approaches. Since Puck is unopinionated, you have full control over how you structure your page management. Maybe you’d prefer a centralized admin dashboard instead of an /edit URL, or maybe you need to separate your editing and rendering environments entirely across two different applications and domains. It’s completely up to you.

Either way, I hope this guide helped you get started with Puck + Contentful—and maybe even sparked some ideas for your next project.

I’d love to hear what you’re building! Whether you have questions, feedback, or just want to bounce around some ideas, here’s how you can connect with me and the Puck team:

Found Puck exciting and useful? Show your support with a 🌟 on GitHub—it helps us keep building the tools you love
Share feedback, explore community plugins, or just hang out with us on Discord 💬
Follow along for updates, development sneak-peeks, and events on Bluesky and X 👀

And of course, if you have any questions or comments, drop them below. I’m always happy to chat!

Top 5 Drag-and-Drop Libraries for React in 2025

Fede Bonel Tozzi — Thu, 20 Feb 2025 13:09:17 +0000

Drag-and-drop is one of those features that seems simple until you actually have to build it. Then, you will suddenly find yourself dealing with event listeners, state management, performance issues, accessibility concerns, and the infamously inconsistent HTML5 drag-and-drop API. All that effort just to let users move something from point A to B—an interaction that's been around since the '80s.

Thankfully, if you're working in React, you don’t have to start from scratch. You’ve got a ton of packages available on NPM to choose from, each with its own trade-offs. Some make drag-and-drop a breeze, while others demand more setup but give you fine-grained control.

We've done more than our fair share of exploring solutions for Puck, our drag-and-drop page builder for React. We needed something flexible, performant, and easy to work with—but finding the right fit wasn’t straightforward. We tried using existing libraries, forking them, and even building our own before settling on an approach with support for CSS grid and flexbox:

If you're looking for a drag-and-drop library to build a visual editor, give Puck a try, and if you like it, we'd love a star on GitHub

After going through that process, we thought: why not share what we learned?

So here’s a breakdown of the top five React drag-and-drop libraries we explored, their pros and cons, and when you should (or shouldn’t) use them. Whether you're building a no-code editor, a layout system, or a kanban board, this list should help you pick the right tool for the job.

TL;DR

If you’re looking for a quick comparison, here’s how each of these libraries stack up against one another:

Library	Customizability	Ease of Use	Maintenance Status	Community Support
dnd-kit	High	Intermediate	Maintained	Large
hello-pangea/dnd	Moderate	Easy	Maintained	Large
pragmatic-drag-and-drop	High	Intermediate	Maintained	Emerging
Gridstack	Moderate	Challenging	Maintained	Niche
formkit/drag-and-drop	Moderate	Easy	Experimental	Niche

🏗 Picking the right drag-and-drop library

Before we get into the list, let’s talk about how to make the right choice.

Engineering is all about trade-offs, and picking a drag-and-drop library is no different. Some libraries are lightweight and flexible, others offer plug-and-play simplicity, and then there are those that look great—until you realize they haven’t been updated in years.

That’s why, to build this list, I focused on balancing four key factors:

Performance – Dragging should feel smooth, not laggy. Poor performance kills the whole experience
Ease of Integration – Does it play well with React? How much setup does it need? Will I have to fight it to make it work in my project?
Flexibility – Can it handle lists, grids, multiple containers? Does it support touch and accessibility? What if I need custom interactions—can I extend it?
Maintenance & Community – Is it actively maintained, or am I about to commit to something that’s already a ghost town?

With that let’s take a look at the best options available today for adding drag-and-drop functionality to your React app.

dnd-kit

dnd-kit is a modern, lightweight toolkit for building drag-and-drop experiences in React. This library takes a unique approach because it doesn’t give you a pre-built DnD system—it's a framework you can use to build your own. This means you get full control over the DnD behavior, styling, and interactions, without being boxed into a rigid API. That flexibility is exactly why we decided to use it for Puck.

✅ dnd-kit’s strengths

🔹 Highly customizable and extensible

One of dnd-kit's biggest strengths is it’s customizability. It’s not a one-size-fits-all solution—it’s a toolkit. This means you get solid defaults out of the box, while also having fine-grained control over almost every aspect of the drag-and-drop experience. You can tweak collision detection algorithms, define custom animations, handle transitions, and adjust behaviors to fit your exact needs.

For example, in Puck, we needed to customize the DnD interactions and collision algorithms to make our experience usable for multi column drag-and-drop across flex and grid containers. We initially went with another library, but quickly realized we couldn’t customize it to the level we needed and switched to dnd-kit.

🔹 Highly performant

While other tools will sometimes drop FPS while dragging, dnd-kit, when used right, feels extremely smooth and satisfying. Animations and rearrangements behave as expected, reinforcing that sense of "physicality" modern DnD interactions rely on.

This strength has made it particularly valuable for our use in Puck. This is because, with design tools, positioning performance and reliable previewing is extremely important, users will likely do this multiple times per minute and will require pixel level precision. Any delay or misplaced drop will frustrate them, break their immersion, and disrupt their workflow. Luckily with dnd-kit, you don’t need to worry about it too much.

🔹 Active maintenance and community support

The community around dnd-kit is also something worth mentioning. With millions of downloads on NPM, it’s an actively maintained project with lots of community support. If you run into issues or need advice, chances are you’ll find answers pretty quickly.

And since it’s actively maintained, you can rely on regular updates and fixes, you’re not going to be stuck with an outdated or abandoned library. Even better, the maintainers accept contributions, including several of our proposals to the experimental version during our Puck integration. That level of community support makes it a solid choice for long-term projects.

🔹 Accessible features

dnd-kit comes with extensible built-in support for multiple input methods, including mouse, keyboard, touch, and pointer events. This means you’re not locked into just one way of interacting with drag-and-drop elements—users can use what they have and works best for them.

It also provides extensible screen reader support, which is a big plus for accessibility. Many drag-and-drop libraries ignore this, but dnd-kit gives you the flexibility to improve usability for everyone, helping your project meet the quality standards you need without requiring you to build everything from scratch.

❌ dnd-kit’s limitations

🔻 Requires more boilerplate

dnd-kit gives you a lot of control, but that comes at a cost—more setup. Unlike some drag-and-drop libraries that offer a quick plug-and-play experience, dnd-kit requires you to put the pieces together yourself. This is great when you need something highly customizable, but if you're just trying to build something simple, like a basic file uploader, it might feel like overkill. If you’re after a quick solution for a straightforward use case, you might want to consider whether the flexibility is worth the trade-off.

🔻 Moderate learning curve

dnd-kit gives you a solid foundation to build drag-and-drop interactions, but it doesn’t hold your hand. While it does provide sensible defaults to help you get started, understanding how it manages interactions and state can take some time—especially if you need to customize it and are new to React or haven’t worked with drag-and-drop libraries before. Having said that, the team is working on a new version that improves the learning experience and will come with a great new docs site.

Since it’s more of a toolkit than a prebuilt solution, you’ll need to think through how you want to structure your drag-and-drop logic. If you're used to libraries that provide higher-level abstractions, dnd-kit might feel a bit lower-level than expected.

🔻 No support for dragging from desktop or other windows

Since dnd-kit isn't built on top of the HTML5 drag-and-drop API, it doesn’t support dragging files or elements between different windows or from the desktop. If your use case involves something like dragging a file from your computer into the app or moving elements between separate browser windows, you’ll need to look into other solutions.

🎯 Best for

dnd-kit is ideal for projects that need fine-grained control over drag-and-drop interactions. If you need to tweak DnD behaviors, implement custom animations, or optimize performance in complex UIs, dnd-kit is a solid choice. However, if your needs are simpler—like a basic file uploader or a to-do list where items just need to be rearranged—dnd-kit might feel like overkill. In those cases, a library with more built-in functionality or one that leverages the HTML5 API could be a better fit.

hello-pangea/dnd

hello-pangea/dnd is a fork of react-beautiful-dnd, the legendary DnD library originally developed by Atlassian. It was designed specifically for list-based drag-and-drop interactions, prioritizing accessibility and smooth animations in kanban style UIs, like Trello.

After Atlassian stopped maintaining react-beautiful-dnd, the community created the hello-pangea/dnd fork. So, while it's still actively maintained, it’s worth noting that Atlassian is no longer involved, serving primarily as a stable fork and great stopgap while exploring other options.

Atlassian has since released a new DnD library, pragmatic-drag-and-drop, which we’ll cover later, so for this section we’ll focus on hello-pangea/dnd.

✅ hello-pangea/dnd’s strengths

🔹 Complete set of out-of-the-box features for lists

The original library was built specifically to power drag-and-drop interactions in Atlassian’s products, so it excels at handling list-based DnD experiences. If you’re building a kanban board, task manager, or any kind of list-based UI, this library is one of the best fits you’ll find.

Compared to other tools in this list, it provides a higher-level abstraction, taking care of all the heavy lifting so you don’t have to implement common behaviors from scratch. Right out of the box, it supports things like drag-and-drop within vertical and horizontal lists, multi item drag-and-drop, and the ability to move items between different lists.

All this makes it a solid option for applications that require a straightforward DnD experience without a lot of customization for sortable lists.

🔹 Feels natural and intuitive

One of the standout aspects of hello-pangea/dnd is how polished and natural the drag-and-drop interactions feel. The library was designed around the idea of physicality—dragging an item should feel like moving a real object, with smooth animations, proper placeholders, and well-weighted collisions.

A lot of work went into optimizing these interactions to feel predictable and satisfying. Items don't just teleport around the screen; they move in ways that respect momentum and spatial constraints, making the experience intuitive for users. For apps where drag-and-drop is a core interaction—like kanban boards or task management tools—this level of polish can go a long way in improving the overall UX.

🔹 Accessible out of the box

hello-pangea/dnd comes with built-in support for multiple input methods, including mouse, keyboard, and touch, making it easier to ensure an inclusive experience without extra work. It also includes screen reader support, which is essential if you're building something that needs to meet accessibility standards.

Compared to other tools in this list, these features are available by default so you don’t have to spend time implementing or configuring them yourself. This can be a real time-saver if you're on a tight deadline, or don’t have experience building accessible interfaces and want a DnD library that handles it for you.

🔹 Gentle learning curve

hello-pangea/dnd is a higher-level abstraction compared to more flexible libraries like dnd-kit, which means you can get up and running faster with less configuration. If all you need is sortable lists, you don’t have to worry about setting up complex drag behaviors or handling reordering logic—it’s already built in. So, if you don’t want to spend time fine-tuning every aspect of the experience, this library can be a solid choice since it lets you focus on the core functionality without unnecessary complexity.

🔹 Battle tested

hello-pangea/dnd is a well-established library with a solid foundation. Originally built as react-beautiful-dnd by Atlassian, it has been used in production by large-scale applications for years. Since it’s been around for a while, you can expect stability and a wealth of resources—whether it’s community discussions, blog posts, or GitHub issues with solutions to common problems.

If you're looking for a battle-tested solution for list-based drag-and-drop, this is one of the most reliable options out there.

❌ hello-pangea/dnd’s limitations

🔻 Limited Experience

hello-pangea/dnd is strictly designed for lists—and that’s where it shines. However, if your use case involves grids, multi-column layouts, or freeform drag-and-drop interactions, this library won’t cut it. There are no plans for grid support, so if you need that kind of flexibility, other tools in this list will probably be a better option.

At Puck, we previously used a custom fork of hello-pangea/dnd with iframe support, but when we wanted to introduce multi-column support to allow users to drag components across CSS Grid and Flexbox layouts, we quickly ran into limitations that made it impractical for our needs.

🔻 Heavy weight and not as efficient as other options

While hello-pangea/dnd is solid for list-based drag-and-drop, it comes with a performance trade-off. The original developers at Atlassian have acknowledged that some design choices—like its high-level abstraction and built-in features—added extra overhead, making it less efficient in certain cases. On top of that, unlike more modular libraries, hello-pangea/dnd requires you to import the entire package to use it. This can make it heavier than necessary, especially for larger applications.

If your project involves complex, deeply nested lists or requires highly optimized page loading times to increase time to interactive (TTI), you might find pragmatic-drag-and-drop (the “official evolution” of this library) or other alternatives to be more lightweight and performant.

🔻 Higher-level abstraction with limited customization

Because hello-pangea/dnd is designed to be easy to use, it trades off flexibility for simplicity. While this is great for straightforward use cases like Kanban boards, it doesn’t give you deep control over DnD interactions. If you need to modify drag behaviors beyond what the library allows, you might hit a wall. In our case at Puck, we needed a more flexible solution that could handle multi-column layouts and custom collision detection algorithms, which led us to explore other options.

For basic list-based drag-and-drop, this isn’t a dealbreaker, but if you need fine-grained control, you may find yourself forking the repository or searching for another solution.

🎯 Best for

hello-pangea/dnd is a solid choice if your use case revolves around lists and you want an easy-to-use solution that works with minimal setup. If you're building a kanban board, task manager, or any UI where users need to reorder items within and across lists, this library gets the job done without much friction.

That said, if you need more flexibility—like grid support, custom animations, or fine-grained control over interactions—then dnd-kit (especially with its sortable package) or pragmatic-drag-and-drop might be better suited for your needs.

pragmatic-drag-and-drop

pragmatic-drag-and-drop is Atlassian’s attempt at solving the problems they ran into with react-beautiful-dnd, their original drag-and-drop library. Unlike its predecessor, this new library takes a headless approach, meaning it doesn’t impose any UI constraints—you’re free to implement your own drag-and-drop interface however you see fit. It’s designed to be more flexible, performant, and framework-agnostic, so it works with any front-end stack, not just React.

The biggest difference this library has with other tools is that it’s built on top of the native HTML5 drag-and-drop API. This is a bold move because the HTML5 DnD API has a reputation for being inconsistent and tricky to work with. Instead of avoiding it, Atlassian built a wrapper around it, abstracting away the common issues and providing a unified, cross-browser API that makes it much easier to work with.

This approach makes pragmatic-drag-and-drop lightweight and efficient, but it also comes with some trade-offs—particularly in terms of user experience. If you’re considering this library, you’ll want to weigh those carefully.

✅ pragmatic-drag-and-drop’s strengths

🔹 Highly customizable and extensible

Because pragmatic-drag-and-drop is headless, you’re not locked into a specific UI or behavior—it just gives you the core drag-and-drop logic, and lets you decide how to present it. This makes it highly customizable since you can integrate it with any components or styles you already have in your code base.

It also provides optional visual outputs as separate packages, meaning that while it doesn’t come with a built-in UI, it does offer some helper utilities for rendering drag previews or drop indicators if you need them. This balance between flexibility and convenience makes it a solid option if you want a lightweight library that doesn’t force you into a specific structure but still provides helpful tools to speed up development.

🔹 Framework agnostic

Unlike most drag-and-drop libraries in this list, pragmatic-drag-and-drop works with any front-end framework. Since it’s based on the native HTML5 drag-and-drop API, it doesn’t rely on React’s internal state management or hooks, making it easy to integrate into Vue, Svelte, Angular, or any other environment.

If you’re working on a multi-framework project or want the flexibility to switch frameworks down the road, this could be a major advantage.

🔹 Highly performant and lightweight

In terms of performance, pragmatic-drag-and-drop was built with special care for it to be fast and lightweight, introducing multiple techniques to bundle only the code you need, and avoid unnecessary rendering in server components. This is partly because it’s built on top of the native HTML5 drag-and-drop API and it doesn’t carry the overhead of other, more feature-heavy libraries.

When compared with dnd-kit, for example, which is also built with high performance in mind, pragmatic-drag-and-drop does come ahead in terms of bundle size. So, if you are building a project where time to interactive is a priority, this option might be the best one for you.

🔹 Accessibility features with defaults

As the official evolution of react-beautiful-dnd, this library also comes with extensible accessibility features right out of the box. The default assistive controls are based on the Atlassian Design System, so if you’re already using that, integration will be seamless. But if you aren’t, you can easily replace those components with your own, or completely redefine how accessibility is provided and take a more customized approach based on your project's needs. This makes it a strong contender if your project has specific accessibility requirements.

❌ pragmatic-drag-and-drop’s limitations

🔻 Limited visual feedback

Because this library relies on the HTML5 drag-and-drop API, it doesn’t offer the same level of smooth, interactive feedback that other libraries do. There’s no live preview placeholder of the dragged element or snapping animations. Instead of a placeholder, it provides a basic drop indicator—a line showing where the item will land once dropped.

For simpler use cases, this might not be a dealbreaker. But for highly interactive applications like page builders or design tools, where users expect to see real-time previews and fluid motion, this can feel limiting. If your project requires a more engaging and visually dynamic drag-and-drop experience, you may need to layer custom animations on top—or consider a different library altogether.

🔻 Lacks comprehensive documentation and community resources

Since pragmatic-drag-and-drop is still relatively new, its documentation and community support aren’t as mature as what you’ll find with more established libraries like dnd-kit or hello-pangea/dnd. While the core functionality is solid, there’s less guidance available—so if you hit an issue, you might find yourself digging through GitHub issues or reading through the source code to figure things out.

If you’re comfortable troubleshooting on your own and don’t mind experimenting, this might not be a huge hurdle. But if you prefer a well-documented API with plenty of community discussions, tutorials, and Stack Overflow answers, you might find the lack of resources frustrating.

🔻 Moderate learning curve

Similar to dnd-kit, pragmatic-drag-and-drop is a headless and framework-agnostic library, which means there’s a bit more of a learning curve compared to plug-and-play solutions. The customization options are powerful, but you’ll need to spend some time getting familiar with its API and how to integrate it effectively into your project.

Additionally, much of the official documentation and examples are built around Atlassian’s design system, so if you’re not using that, you might need to spend extra time adapting the examples to your own setup. Depending on your experience, this could be a minor inconvenience or a bigger hurdle when first getting started.

🔻 License considerations

While Apache 2.0 is a widely used and permissive license, it’s not as open-ended as the MIT license that some of the other libraries on this list use. If your project has specific licensing requirements, it's worth taking a moment to review the terms and ensure it aligns with your intended use.

🔻 Unconventional approach to open source

Unlike most open-source projects, Atlassian doesn’t fully embrace the traditional open-source model. Their development happens internally, with updates being synchronized to GitHub by a bot, meaning there’s no public roadmap or direct insight into upcoming changes. While the project is technically open-source, this lack of transparency could be a drawback if you’re looking for a library with active community involvement or want to contribute to its development.

🎯 Best for

pragmatic-drag-and-drop shines in applications that require lightweight drag-and-drop functionality, especially in scenarios involving lists, trees, or container-based interactions. It’s perfect for use cases like task management boards or file organizers, where simple drag-and-drop is enough. However, the library’s limited visual feedback makes it less suitable for more complex use cases, particularly if they involve grid or flex based layouts. So, if your project relies heavily on complex multicolumn layouts or needs more interactive feedback (such as animating items as they are dragged), you might want to explore other options in this list.

Gridstack.js

Gridstack.js is a drag-and-drop library built specifically for grid-based layouts. If you're building interactive dashboards or anything that requires draggable and resizable grid items, this library takes care of most of the heavy lifting right out of the box.

This is also the oldest library on this list, having been around for nearly 11 years. It originally started as a jQuery-based project before migrating to vanilla JavaScript. That long history means it’s been used in a variety of real-world applications and is likely to stick around.

That said, this also comes with some trade-offs. The transition from jQuery wasn’t entirely seamless, and some API design choices still carry legacy baggage. While the library is still actively maintained, parts of it might feel dated or tedious compared to more modern React-focused solutions.

✅ Gridstack’s strengths

🔷 Complete set of out-of-the-box functionalities for grids

Like hello-pangea/dnd, Gridstack.js is a higher-level abstraction, but instead of focusing on lists, it’s designed specifically for grid-based layouts. While tools like dnd-kit require additional work to support grid behavior, Gridstack handles all that for you, so you can focus on configuration rather than implementation.

Right out of the box, it provides grid drop zones with configurable rows and columns, drag-and-drop positioning within a grid, and resizable grid items that snap to the layout structure. So, if your app depends on draggable grids and you’d rather not build that functionality from scratch, Gridstack is a solid choice that can save you a lot of development time.

🔷 Mature library with long-term support

Gridstack.js has been around for over a decade, making it one of the most battle-tested libraries in this list. Its longevity means it's been used in a wide range of real-world applications, from internal tools to production dashboards, and it continues to receive updates and improvements. Unlike some libraries that pop up and disappear after a few years, Gridstack has shown long-term stability, making it a safer bet if you’re looking for a drag-and-drop solution that won’t suddenly be abandoned.

🔷 Framework agnostic

Just like pragmatic-drag-and-drop, Gridstack.js is designed to work with any JavaScript framework—or even without one. This gives you flexibility if you're working in a mixed environment or need a solution that isn’t tightly coupled to React. It has official wrappers for Angular, Ember, Aurelia, and Rails but at its core, it's a vanilla JavaScript library. This means you can integrate it into different projects without being locked into a specific ecosystem.

If you need a stable grid drag-and-drop experience, and you want a long-term solution that can be adapted across different frontend stacks, you should seriously consider using Gridstack.

❌ Gridstack’s limitations

🔻 Steep learning curve for React integration

While Gridstack.js is a powerful tool for grid-based drag-and-drop interactions, integrating it with React can feel unintuitive. The library was originally built with jQuery in mind, and while it has since transitioned to vanilla JavaScript, many of its API design choices still reflect those roots. Instead of working with standard React patterns like props and state, you have to inject the grid manually by manipulating the DOM directly using HTML IDs and selectors; and you’ll also have to use objects and classes to handle the grid state and its configurations.

For React developers, this can feel out of place and lead to more complex, less idiomatic code. The team has discussed releasing an official React wrapper to improve the experience, but there has been community feedback suggesting that the current setup can be frustrating. If you're comfortable working closer to the DOM or have experience with non-React libraries, this might not be a dealbreaker. But if you’re looking for a more seamless React-first solution, Gridstack might require some extra work to integrate smoothly.

🔻 Sparse documentation and small community

Gridstack.js has been around for a long time, but its documentation is relatively minimal. While there are some examples available, they don’t always cover more complex use cases, leaving you to figure things out through trial and error. This wouldn’t be as much of an issue if there were an active community to turn to, but Gridstack’s user base is fairly niche. That means fewer online discussions, tutorials, or Stack Overflow threads to help troubleshoot issues. If you're used to working with well-documented libraries with strong community support, integrating Gridstack into your project might feel like more of a solo effort.

🔻 Limited to grid-based layouts

Gridstack.js is built specifically for grid-based drag-and-drop interactions, which means it doesn’t support other layout types like flexbox out of the box. If your project requires a mix of grid and flex layouts or more fluid positioning, you’ll need to work around these limitations or consider a different library. While this isn’t necessarily a dealbreaker if you’re working on a dashboard-style UI, it does mean you’re locked into a specific way of handling layouts. If you need more flexibility, other libraries might be a better fit.

🎯 Best for

Gridstack.js is a solid choice if your project is heavily focused on grid-based layouts and you need out-of-the-box item resizing. It’s particularly useful for applications like dashboards, widget-based UIs, or any interface where users need to rearrange elements within a strict grid structure.

However, if you're working in a React environment, integration can be a bit clunky due to its JavaScript-first design and reliance on selectors, classes, and objects. If you need a more seamless React experience with drag-and-drop inside grids, dnd-kit or pragmatic-drag-and-drop might be a better fit depending on your flexibility and performance needs.

formkit/drag-and-drop

formkit/drag-and-drop is a relatively new, lightweight library developed by the team behind FormKit, a form framework for Vue. Unlike traditional drag-and-drop libraries that manipulate the DOM directly, this one takes a different approach: instead of physically moving elements around, it updates a underlying reactive data model that you provide. This means that rather than worrying about manually reordering elements, you let the library handle updates to your data structure, making it feel more like a natural extension of reactive frameworks.

It’s framework-agnostic but comes with thin wrappers for both React and Vue, making it easier to integrate. While it’s still in early stages and hasn’t hit a 1.0 release, it’s gaining traction for its simple, intuitive approach to drag-and-drop. If you’re looking for a minimal, easy-to-use solution that plays well with React state, this library might be worth keeping an eye on.

✅ formkit/drag-and-drop’s strengths

🔹 Lightweight

One of the biggest advantages of formkit/drag-and-drop is its size—it clocks in at just ~5KB gzipped. Compared to some of the heavier libraries on this list, this makes it one of the smallest options available. If bundle size is a priority for your project, this is a strong contender. Alongside pragmatic-drag-and-drop, it’s one of the most minimalistic options, helping to keep your app lean without unnecessary overhead.

🔹 Plugin Support

Despite being a minimal library, formkit/drag-and-drop includes a plugin system that lets you extend its functionality without adding unnecessary bloat. This means you can keep the core lightweight while selectively introducing features as needed.

Out of the box, it provides plugins for customizing item previews, modifying drop selection behavior, and adding animations. These built-in extensions make it easier to tweak the drag-and-drop experience without writing custom logic from scratch. While the plugin ecosystem is still relatively small, it offers a solid foundation for modular extensions—helping bridge the gap between fully headless solutions and more opinionated, feature-rich libraries.

🔹 Gentle learning curve

Among all the libraries in this list, formkit/drag-and-drop has the simplest setup for a React application. Instead of manually handling drag-and-drop logic, you just use a hook that connects directly to your data model. The library then provides a state-driven way to render your items, along with a ref for the parent drop container.

This approach keeps everything declarative and React-friendly, making it easy to integrate without a lot of boilerplate. If you just need a straightforward drag-and-drop experience, it works right out of the box. And if you need more complexity later on, you can introduce additional functionality gradually without refactoring your entire setup.

❌ formkit/drag-and-drop’s limitations

🔻 Limited docs and unclear API

Since formkit/drag-and-drop is still relatively new, its documentation is pretty minimal. While the basics are covered, there aren’t a lot of clear examples for handling more complex use cases. This means that certain features that are standard in other libraries, may require some extra trial and error to implement in this one.

If you’re building something straightforward, this isn’t a huge issue. But if you need deeper customization, expect to spend some time digging through the source code or experimenting with different configurations. The library is evolving, so this might improve in the future, but for now, it’s something to keep in mind.

🔻 Small and niche community

As of now, formkit/drag-and-drop is still in its early stages, currently at version 0.3. This means the community around it is relatively small, and finding discussions, third-party tutorials, or Stack Overflow answers can be a challenge.

While FormKit itself has a solid reputation in the Vue ecosystem, this particular library is still growing. If you run into issues or need advanced support, you may have to rely on the official docs (which are limited) or experiment on your own. It’s not a dealbreaker, but it’s something to consider if you prefer libraries with a more established user base.

🔻 Limited accessibility

While formkit/drag-and-drop does include some basic screen reader support, it lacks proper keyboard navigation and has some inconsistencies on mobile. For accessibility-focused projects, this could be a dealbreaker, especially if you need users to interact with drag-and-drop elements without a mouse.

Since accessibility can be tricky to implement from scratch, you might find yourself needing to build custom workarounds to fill in the gaps. This is an area where more mature libraries like dnd-kit or hello-pangea/dnd have the upper hand, as they provide better and more stablished cross-device support.

🎯 Best for

As of now, formkit/drag-and-drop is a solid choice if you need basic drag-and-drop functionality without a lot of setup. It works well for simple use cases like moving items between containers or reordering lists, especially if you’re looking for something lightweight and easy to integrate. However, for more complex interactions, like those required in design tools or highly customized layouts, it may still feel limited. If you need fine-grained control over DnD behaviors or a library with long-term stability, something like dnd-kit would be a better option.

Also, since it’s still an early-stage library, the API is subject to change, and its promises around performance and bundle size could shift over time. If you need a stable solution with an established track record, this might not be the best choice—at least for now.

🔚 Wrapping Up

Choosing the right drag-and-drop library isn’t as straightforward as it seems. As we saw in this list, each option comes with its own strengths, trade-offs, and best use cases, and like everything in engineering, the “best” choice ultimately depends on your specific needs.

If you're exploring drag-and-drop solutions because you’re working on a page builder, a dashboard, or any app that needs a powerful visual editor, you might want to check out Puck—we built it to make embedding a flexible visual editor into your app as seamless as possible.

🚀 We’d love to hear your thoughts! If you have feedback on this breakdown, know of other libraries we should check out, or just want to chat about drag-and-drop and visual editing, come say hi:

⭐ Support us on GitHub by dropping a star

💬 Join the conversation on Discord

🐦 Follow us for updates on X & Bluesky

And of course, if you have any questions or comments, drop them below—always happy to keep the conversation going!

Advanced Layouts with Puck 0.18: Harnessing Grid and Flex Containers

Fede Bonel Tozzi — Fri, 14 Feb 2025 14:35:12 +0000

Puck is the open-source visual editor for React, that you can embed in any application to create the next generation of page builders and no-code products. Give us a star on GitHub! ⭐️

Drag-and-drop page-builders are everywhere, but getting them to work seamlessly across different layouts—especially complex CSS Grid and Flexbox structures—has always been a challenge. With Puck 0.18, that just got a lot easier.

This update introduces a revamped drag-and-drop engine designed to work naturally across any CSS layout. Instead of forcing elements into rigid structures, you now have full control over the styles of DropZones and their children to fit your design needs, and let you do things like this:

With the new drag-and-drop engine, you can add any CSS layout however you want to your editor—but some patterns can make the process much smoother. That’s why in this post, we’ll go over some common patterns I’ve found useful for adding CSS Grid and Flex support to your editors, along with best practices to help you get the most out of Puck’s new engine.

Before we get started, I’ll assume you have a basic understanding of Puck and how it works. If you’re new here, no worries—you’re welcome to follow along! However, I’d recommend checking out the Getting Started guide first to familiarize yourself with the basics, as well as the 0.18 blog post to learn about the new features in this version.

Grid patterns
1. Grid container pattern
2. Grid container - Grid Item pattern
3. Grid container - Any item pattern
4. Grid layout pattern
Flex patterns
1. Flex container pattern
2. Flex container - Flex item pattern
3. Flex container - Any item pattern
Best practices
1. Add dynamic padding for editing
2. Prevent unwanted layout shifts
3. Give hints with collisionAxis

🍱 Grid patterns

CSS Grids are built for structured, multi-column layouts with precise control over item placement. Unlike Flexbox, which distributes items dynamically based on content size, Grids let you define fixed or flexible tracks, making them a great fit for dashboards, forms, bento layouts, and any design where the number of rows and columns matters.

With Puck’s drag-and-drop engine, you can give users full control over CSS rules so they can build grids however they like. But in most cases, you'll want to guide them through the process to keep things intuitive for all levels of experience. Sometimes that means letting them define the number of columns and rows in a grid freely; other times, it makes more sense to provide a set of predefined grid designs from which to choose from.

With this in mind, in this section I’ve gathered four patterns I’ve found especially useful for adding grids to build intuitive and flexible page-building experiences across a variety of use cases.

Grid container pattern

The Grid container pattern is the foundation of all grid-based layouts in Puck. With this approach, the grid DropZone itself defines the grid layout, so that all elements inside follow a predefined number of rows or columns. This is useful when you want to give control over the layout container and need a regular arrangement of elements in columns and rows, so it’s ideal for things like lists and content grids.

To set it up you need to follow these steps:

1. Define a new component in your Puck config for the grid

const config = {
  components: {   
    // Define your Grid component for grid layouts
    Grid: {
      //... next steps here
    },
  },
};

2. Optionally, add fields to let users configure the grid—for example, you could add fields to set rules like the number of columns and rows

const config = {
  components: {
    Grid: {
      // Add fields to configure the numbers of rows/columns in the grid
      fields: {
        columns: { type: "number" },
        rows: { type: "number" },
      },
    },
  },
};

3. Finally, render a DropZone inside the Grid component, applying a display: grid CSS rule and any other desired layout rules or user-defined settings

const config = {
  components: {
    Grid: {
      //... existing config

      // Render the DropZone as a CSS grid
      render: ({ columns, rows }) => {
        return (
          <DropZone
            zone="grid-zone"
            style={{
                display: "grid",
              gridTemplateColumns: `repeat(${columns || 1}, 1fr)`,
              gridTemplateRows: `repeat(${rows || 1}, auto)`,
            }}
          />
        );
      },
    },
  },
};

If you followed these steps, you’ll now be able to navigate to the editor in the browser, drag and drop a Grid, set the number of columns and rows for it, and drop items inside to automatically snap them to the grid structure:

As you can see, this pattern works great for structured layouts, but if you need more flexibility—like controlling how individual items are placed within the grid, or allow the user to define custom multi-column layouts—you should check out the Grid container - Grid item pattern, which we’ll cover next.

Grid container - Grid item pattern

The Grid container - Grid item pattern builds on the Grid container pattern by giving you more flexibility in how items are arranged. Instead of enforcing a uniform layout where every item spans the same number of rows and columns, this approach lets users break grids into distinct sections with their own configurable drop zones.

The key to achieve this is adding a GridItem component to your config. This component should render a DropZone, provide fields to set how many rows and columns that DropZone spans in the grid, and be restricted to use only inside Grid components. With that in place you would allow users to:

Drag and drop Grid Item zones inside a Grid
Set how many columns and rows each zone should occupy
Organize the layout visually by dragging and dropping zones around
Drag and drop content into each zone

That’s why, with this pattern, you can define custom layouts directly in the editor. For example, you could create a layout with a navbar zone that spans all columns at the top, a table of contents that spans all rows on the left, and a main content section on the right.

To implement this pattern, follow these steps:

1. Add a Grid component to your Puck config

const config = {
  components: {
    //... existing config

    // Define a Grid component
    Grid: {
      render: () => {
        return (
          <DropZone
            zone="grid-zone"
            style={{
              display: "grid",
              gridTemplateColumns: `repeat(3, 1fr)`,
            }}
          />
        );
      },
    },
  },
};

2. Assign the allow prop on the Grid DropZone to an array containing only the name of your GridItem component. This will only allow GridItems inside the grid

const config = {
  components: {
    Grid: {
      render: () => {
        return (
          <DropZone
            //... existing config

            // Only allow grid items inside the grid
            allow={["GridItem"]}
          />
        );
      },
    },
  },
};

3. Add the GridItem component to your Puck config

const config = {
  components: {
    //... existing config

    // Define your Grid Item component
    GridItem: {
      //... next steps here
    },
  },
};

4. Remove the default wrapping element Puck adds around draggable components for the GridItem by enabling the inline parameter. This will remove the Puck wrapper and allow you to style the grid items as direct children of the grid they are dropped in

const config = {
  components: {
    //... existing config

    GridItem: {
      // Remove the default element wrapper
      inline: true,
    },
  },
};

5. Add fields to the GridItem component to define the number of columns and rows each item should span

const config = {
  components: {
    GridItem: {
      //... existing config

      // Add fields for the number of columns/rows the item should span
      fields: {
        columns: { type: "number" },
        rows: { type: "number" },
      },
    },
  },
};

6. Render the DropZone inside the GridItem with the number of columns and rows it should span. Also, since you previously enabled the inline parameter, you must pass the puck.dragRef to the DropZone to let Puck know it should be treated as a draggable element

const config = {
  components: {
    GridItem: {
      //... existing config

      // Render the DropZone with the number of columns/rows it should span
      render: ({ columns, rows, puck }) => {
        return (
          <DropZone
            ref={puck.dragRef}
            zone="grid-item-zone"
            style={{
              gridColumn: `span ${columns || 1}`,
              gridRow: `span ${rows || 1}`,
            }}
          />
        );
      },
    },
  },
};

7. Finally, disallow GridItems to be nested inside other GridItems to provide a better experience while dragging elements around grids

const config = {
  components: {
    GridItem: {
      render: ({ columns, rows, puck }) => {
        return (
          <DropZone
            //... existing config

            // Disallow GridItems inside
            disallow={["GridItem"]}
          />
        );
      },
    },
  },
};

After following these steps, you should now be able to navigate to the browser, drag and drop a Grid, add GridItems inside, set the number of columns and rows each item should span, and drag any component inside these grid zones to automatically adjust it to fit the layout.

This pattern is great when you want to provide full control over layout structure, but if you just need a way for users to drop any component into a grid and still define how much space it should take up inside, the Grid container - Any item pattern is a better fit.

Grid container - Any item pattern

The Grid container - Any item pattern is a more flexible approach to working with grids, allowing any component to be placed inside while still letting users control how much space each item takes up. Instead of limiting grid items to a specific type, this pattern enables any component to define their own grid placement dynamically when dropped inside of a grid.

With this pattern, users can:

Drop any component inside a grid
Define how many rows and columns each item should span
Keep components fully functional outside of grids by hiding the rows and columns fields

The key here is using dynamic fields to adjust component settings based on their parent. If a component is inside a Grid, it should show columns and rows fields to let users define its span. If it’s outside, those fields should stay hidden.

To implement this pattern, follow these steps:

1. Add a Grid component to your Puck config

const config = {
  components: {
    //... existing config

    // Define a Grid component
    Grid: {
      render: () => {
        return (
          <DropZone
            zone="grid-zone"
            style={{
              display: "grid",
              gridTemplateColumns: `repeat(3, 1fr)`,
            }}
          />
        );
      },
    },
  },
};

2. Use the resolveFields API on any component to dynamically show the columns and rows fields when placed inside a Grid parent, hiding them when the component is used outside a grid

const config = {
  components: {
    //... existing setup

    AnyComponent: {
      // Remove the default element wrapper
      inline: true,

      // Use dynamic fields to show "Columns" and "Rows" only when inside a Grid
      resolveFields: (data, { parent }) => {
        let fields = {
          //... existing fields
        };

        if (parent?.type === "Grid") {
          fields = {
            ...fields,
            columns: { type: "number" },
            rows: { type: "number" },
          };
        }

        return fields;
      },

      // Render the component with the correct grid placement
      render: ({ columns, rows, puck }) => {
        return (
          <div
            ref={puck.dragRef}
            style={{
              gridColumn: `span ${columns || 1}`,
              gridRow: `span ${rows || 1}`,
            }}
          >
            Any Component
          </div>
        );
      },
    },
  },
};

PRO TIP: If you find yourself repeating this setup multiple times for any components you wish to drop inside a grid, consider creating a withGrid(componentConfig) function that adds the resolveFields setup above to avoid code repetition

After setting this up, you can navigate to the editor, drop any component into any grid, adjust its column and row span, and see the layout update in real time. If the component is moved outside of the grid, those fields will disappear, keeping it adaptable to different layouts.

This pattern works great if you want to allow any item inside a grid while still controlling how each item is positioned. However, there are times when you might want to restrict users to a specific set of predefined grid layouts so they don’t have to worry about design details. For those cases, the Grid layout pattern is the best option.

Grid layout pattern

The Grid layout pattern allows users to choose from predefined grid layouts instead of manually adjusting each item's placement or setting up the layout themselves. This is useful when you want to streamline the page-building process and ensure design consistency while still offering flexibility.

The key difference from the Grid container - Any item and Grid container - Grid item patterns is that here, the grid itself determines how components are arranged based on multiple pre-implemented designs, rather than the nested components defining their own placement based on user input.

With this pattern, users can:

Select a grid design from a predefined set of grid layouts
Drop any components into the grids
Maintain a clean and predictable design without manual configuration

To implement this pattern, follow these steps:

1. Define a Grid component with a layout select field to allow users to choose a predefined grid design. Each option’s value should be the CSS class that implements that specific design

// Import designs
import "./Editor.css";

const config = {
  components: {
    Grid: {
      fields: {
        // Add a layout select input to choose a certain grid design
        layout: {
          type: "select",
          options: [
            { label: "Hero", value: "hero-layout" },
            { label: "Content List", value: "content-list-layout" },
          ],
        },
      },
      // Read the layout design to style the dropzone based on it
      render: ({ layout }) => {
        return (
          <DropZone zone="grid-zone" className={`grid ${layout || ""}`} />
        );
      },
    },
  },
};

2. Define the CSS classes for your grid layouts so that each option applies a different design to the grid

/* ./Editor.css */

/* Base grid styles */
.grid {
  display: grid;
}

/* Hero section layout */
.hero-layout {
  grid-template-columns: 1fr 1fr;
  gap: 16px;
}

/* Layout for a list of content */
.content-list-layout {
  grid-template-columns: repeat(4, 1fr);
  gap: 8px;
}

Once set up, users can drop components into a grid without worrying about manual positioning. They’ll be able to select a layout design from the list of options you provide and the grid items will automatically adjust to match the chosen design.

This is ideal for use cases where structure and consistency are important, like root-level page layouts, forms, or articles.

↩️ Flex patterns

Flexbox is all about dynamic, content-aware layouts. Unlike CSS Grids, which are great for structured designs with fixed tracks, Flexbox shines when you need elements to adjust based on their content and available space. It’s perfect for things like responsive lists and card layouts where items should naturally grow, shrink, or wrap as needed.

Once again, with Puck, you could give users full control over Flexbox CSS rules so that they can fine-tune every detail on their pages. But most of the time, when creating a page builder, you’ll want to abstract away from those complexities so that anyone can create pages without worrying about layout intricacies. After all, your user won’t always be a developer, and Flexboxes are famous for tripping over even the most seasoned front-end engineer from time to time.

That’s why, in this section, I’m sharing three patterns you can use to build intuitive, flexible page-building experiences with Flexbox in Puck.

Flex container pattern

The Flex container pattern is the simplest way to structure a layout using Flexbox in Puck, and it’s the basis of all other flex patterns. In this approach, the DropZone itself defines the flex behavior, so all elements inside follow the container’s layout rules. This works well when you want a flexible, row-based or column-based structure where items automatically adjust based on their content and available space. It’s especially useful for things like horizontal navigation bars, stacked sections, or dynamic lists.

To set it up, follow these steps:

1. Define a new component in your Puck config for the Flex container

const config = {
  components: {
    // Define your flex container
    FlexContainer: {
      //... next steps here
    },
  },
};

2. Optionally, add fields to let users configure the flex behavior—for example, you might allow them to control flex-direction

const config = {
  components: {
    FlexContainer: {
      // Add fields to configure flex behavior
      fields: {
        direction: {
          type: "select",
          options: [
            { label: "Row", value: "row" },
            { label: "Column", value: "column" },
          ],
        },
      },
    },
  },
};

3. Render a DropZone inside the Flex container, applying display: flex and any user-defined settings

const config = {
  components: {
    FlexContainer: {
      //... existing config

      // Render the DropZone as a flex container with user-defined settings
      render: ({ direction = "row" }) => {
        return (
          <DropZone
            zone="flex-zone"
            style={{
              display: "flex",
              flexWrap: "wrap",
              flexDirection: direction,
            }}
          />
        );
      },
    },
  },
};

If you followed these steps, you should now be able to navigate to the editor, drop a Flexbox component, add some items inside, modify the direction of the container, and see the elements automatically arrange according to the user’s settings:

This pattern is great for simple, responsive layouts where all items flow naturally within a flexible container. If you need more control over individual item behavior—such as setting different flex-grow or alignment rules per item—you’ll want to explore the Flex container - Flex item pattern next.

Flex container - Flex item pattern

The Flex container - Flex item pattern is a simple yet powerful way to structure layouts using Flexbox. With it, you define a Flex container that holds Flex items where each item acts as a section where users can drop other components. This makes it useful for setting up flexible page structures—like a sidebar and main content area—or components that need to adapt to different screen sizes, such as a card with three horizontal sections that wrap when space is limited.

The key to this pattern is introducing a Flex Item component that wraps each child inside the Flex container. This component, then, provides controls for flex-grow, flex-shrink, and flex-basis, allowing users to tweak layout behavior visually inside the editor. With that in place you would allow users to:

Drag and drop Flex Item zones inside a Flex container
Control how each zone should grow, shrink, and take up space
Organize the layout visually by dragging and dropping zones around
Drag and drop content into each zone

To implement this pattern, follow these steps:

1. Define a new component in your Puck config for the Flex container

const config = {
  components: {
    // Define a Flex container component
    FlexContainer: {
      render: () => {
        return (
          <DropZone
            zone="flex-zone"
            style={{
              display: "flex",
              flexWrap: "wrap"
            }}
          />
        );
      },
    },
  },
};

2. Restrict the container to only allow FlexItems inside

const config = {
  components: {
    FlexContainer: {
      render: () => {
        return (
          <DropZone
            zone="flex-zone"
            // Only allow FlexItem components inside
            allow={["FlexItem"]}
            style={{
              display: "flex",
              flexWrap: "wrap"
            }}
          />
        );
      },
    },
  },
};

3. Define the FlexItem component

const config = {
  components: {
    FlexItem: {
      // Remove the default wrapper around the component to style it as a child
      // of a flexbox
      inline: true,
    },
  },
};

4. Add fields for controlling the flex properties of the FlexItems

const config = {
  components: {
    FlexItem: {
      fields: {
        grow: { type: "number" },
        shrink: { type: "number" },
        basis: { type: "text" },
      },
    },
  },
};

5. Render the DropZone inside the FlexItem, applying any required flex properties

const config = {
  components: {
    FlexItem: {
      render: ({ grow, shrink, basis, puck }) => {
        return (
          <DropZone
            ref={puck.dragRef}
            zone="flex-item-zone"
            style={{
              flexGrow: grow ?? 0,
              flexShrink: shrink ?? 1,
              flexBasis: basis ?? "auto",
            }}
          />
        );
      },
    },
  },
};

6. Finally, prevent nesting Flex Items inside each other

const config = {
  components: {
    FlexItem: {
      render: ({ grow, shrink, basis, puck }) => {
        return (
          <DropZone
            disallow={["FlexItem"]} // Prevents nesting
            ref={puck.dragRef}
            zone="flex-item-zone"
            style={{
              flexGrow: grow,
              flexShrink: shrink,
              flexBasis: basis,
            }}
          />
        );
      },
    },
  },
};

Once set up, you’ll be able to drop a FlexContainer onto the page, add FlexItems inside, and adjust their behavior using the flex properties. You can then place any other components inside these sections, letting them adapt naturally within the layout.

This pattern is ideal when you need a flexible page layout, but if you’re looking for a way to add any component inside a flex container and still be able control it’s flex properties dynamically, the Flex container - Any item pattern might be a better fit.

Flex container - Any item pattern

The Flex container - Any item pattern is a more adaptable approach to using flex layouts, allowing any component to be placed inside while giving users control over how each item behaves within the flex container.

With this pattern, users can:

Drop any component inside a flex container
Control how items grow, shrink, and take up space
Keep components fully functional outside of flex containers by hiding flex-specific controls

The key here is using dynamic fields to expose flex properties like flex-grow, flex-shrink, and flex-basis only when a component is inside a Flex container. Outside of it, these fields should remain hidden to avoid unnecessary complexity.

To implement this pattern, follow these steps:

1. Define a new component in your Puck config for the Flex container

const config = {
  components: {
    // Define a Flex container component
    FlexContainer: {
      render: () => {
        return (
          <DropZone
            zone="flex-zone"
            style={{
              display: "flex",
              flexWrap: "wrap",
            }}
          />
        );
      },
    },
  },
};

2. Define any component that can be placed inside a flex container, dynamically adjusting its flex related fields based on the parent container

const config = {
  components: {
    //... existing setup

    AnyComponent: {
      // Remove the default element wrapper
      inline: true,

      // Use dynamic fields to show "Flex Grow," "Flex Shrink," and "Flex Basis" 
      // only when inside a FlexContainer
      resolveFields: (data, { parent }) => {
        let fields = {
          //... existing fields
        };

        if (parent?.type === "FlexContainer") {
          fields = {
            ...fields,
            flexGrow: { type: "number" },
            flexShrink: { type: "number" },
            flexBasis: { type: "text" },
          };
        }

        return fields;
      },

      // Render the component with the configured flex behavior
      render: ({ flexGrow, flexShrink, flexBasis, puck }) => {
        return (
          <div
            ref={puck.dragRef}
            style={{
              flexGrow: flexGrow ?? 1,
              flexShrink: flexShrink ?? 1,
              flexBasis: flexBasis ?? "auto",
            }}
          >
            Any Component
          </div>
        );
      },
    },
  },
};

PRO TIP: If you plan to use this setup for multiple components, consider creating a withFlex(componentConfig) function that adds the resolveFields setup above to avoid code repetition

Once set up, users can drop any component into a flex container, tweak its growth and shrink behavior, and see changes in real-time. If the component is moved outside of the flex container, those controls will disappear, keeping it adaptable for different layouts.

This pattern is great for flexible, dynamic layouts where elements need to adjust their sizes based on available space.

🔷 Best practices

Beyond the patterns we’ve covered for integrating CSS Grid and Flexbox, there are a few best practices or tips that can help improve the overall drag-and-drop experience and make your editor feel smoother and more intuitive.

Add dynamic padding for editing

When working with nested layouts in the editor, selecting the right component with your cursor can get tricky—especially if DropZones are tightly packed. A simple way to improve usability is by adding space around DropZones only when the page is being edited. To do this, you can use the puck.isEditing render prop, to add temporarily padding around DropZones, making it easier to grab and move entire groups of nested components without accidentally selecting inner ones:

const config = {
  components: {
    NestedComponent: {
      render: ({ puck }) => {
        return (
          <DropZone
            zone="dropzone-with-padding"
            // If rendering in the editor, add padding, otherwise don't add any
            styles={{ padding: puck.isEditing ? "16px" : undefined }}
          />
        );
      },
    },
  },
};

Prevent unwanted layout shifts

Nothing disrupts a drag-and-drop experience more than unexpected layout shifts while dragging elements around. To keep things predictable, you can use the allow and disallow props on your DropZones to control where components can be placed, that way, you can prevent seeing whole lists or containers move elements around when you just wanted to move a page header to the top of your canvas:

const config = {
  components: {
    Header: {
      render: () => {
        return <h1>My header</h1>;
      },
    },
    ProductsList: {
      render: ({ puck }) => {
        return (
          <DropZone
            zone="product-zone"
            // Only allow product items in this zone
            allow={["ProductItem"]}
          />
        );
      },
    },
    ProductItem: {
      render: () => {
        return <div>Product</div>;
      },
    },
  },
};

We used this in the Grid container - Grid item and Flex container - Flex item patterns to avoid nesting of sections and provide a better experience when moving them around the container.

Give hints with `collisionAxis`

Use the DropZone collisionAxis prop to give Puck a hint about which direction your components flow.

By default, Puck will automatically identify the most likely drag direction based on your DropZone’s CSS properties, but sometimes you might have particular behavior that Puck can’t interpret. For example, if you have a flex container that doesn’t wrap, setting an x (horizontal) collision axis will help it to know where it should try to add new elements:

const config = {
  components: {
    Example: {
      render: () => {
        return (
          <DropZone
            zone="my-content"
            collisionAxis="x"
            style={{ display: "flex", flexWrap: "noWrap" }}
          />
        );
      },
    },
  },
};

Ready to start building with Puck?

In this article, we covered some key patterns and best practices to help you build intuitive, flexible visual editors with Puck and take advantage of all the new features v0.18 introduces. Whether you're working with grids or flex layouts, these techniques should give you a solid foundation to create great editing experiences.

We’d love to hear what you're building! If you have questions, want to suggest improvements, contribute, or just bounce around ideas, here’s how you can get involved:

🌟 Star Puck on GitHub to show support and help others discover it.

🤝 Join our Discord to chat with the community and share your work.

📢 Follow Puck on X and Bluesky for updates, sneak peeks, and tips.

Have thoughts or feedback? Drop a comment—we’re always up for a good discussion.

Happy building! 🚀

Top 5 Page Builders for React in 2026

Fede Bonel Tozzi — Sat, 08 Feb 2025 00:03:50 +0000

You're building a modern web app, and everything is going smoothly—until a client says, “I want to customize the layout myself.” Suddenly, you’re faced with a monumental challenge: building a page builder.

It sounds simple—drag, drop, tweak—but we know better. A real page builder involves complex drag-and-drop logic, forms, and integration with both your back and front end components. It’s not just hard—it’s a lot.

Yet, page builders are non-negotiable in a lot of projects. They’re the missing link in headless CMS stacks, and a core part of many low-code tools, letting users create and edit layouts without writing code. But, thankfully, you don’t have to build one from scratch—React’s ecosystem offers plenty of options.

So, which ones are worth your time? I’ve narrowed it down to five top picks to help you choose the right tool for your project. Whether you’re putting the head back on your headless CMS, building a no-code platform, or a layout editor, this list will help you find the right tool for the job.

Choosing the Right Page Builder
Puck - Visual Editor for React
Storyblok - Headless CMS
Builder.io - Headless CMS
Tiptap - Visual Editor
GrapesJS - Visual Editor

⚖ Choosing the Right Page Builder

Before we get into it, it’s important to understand something: Not all page builders are created equal. The most critical factor when selecting one? Flexibility.

Flexibility means more than just drag-and-drop widgets or customizable layouts. The ideal page builder adapts to your needs without locking you into rigid patterns, headless CMS vendors, or a bloated API. It should:
- Let users create beautiful, versatile designs intuitively
- Empower developers to integrate it seamlessly into their apps, match their website’s unique look and feel, and even tweak the UX for specific use cases
- Enable you to own your data, so that your web pages aren’t stuck with a proprietary vendor

In short, a great page builder doesn’t just work; it works with you. But let’s be real, every tool has tradeoffs. The trick is finding the one that balances ease of use, integration, customization, and long-term flexibility for your project.

Ready to find the perfect fit? Let’s dive in!

Puck - Visual Editor for React

Puck is an embeddable, modular, open-source visual editor for React with built-in support for complex drag-and-drop page building.

While other headless options in this list, like GrapesJS, provide a barebones page building experience, and tools like Builder.io and Storyblok offer fully-fledged CMS platforms, Puck aims to bridge the gap. It combines an extendable ready-to-use page editor with a decoupled page export model, giving you flexibility without locking you into a specific backend or proprietary ecosystem.

With Puck, you don’t need to build an editor from scratch, commit to a propietary CMS, or go through a multi-step setup. In fact, you don’t even need a CMS at all if you don’t want one. Getting started is as simple as rendering the <Puck /> component and passing a config object that defines which components you want to make draggable.

It’s so straightforward that this is the only tool on this list where I can show you the setup in just a few lines of code:

// This renders your editor:
<Puck
  // Your initial data here
  data={initialData}
  // Your draggable components here
  config={{
    components: {
      Header: {
        fields: {
          text: {
            type: "text",
          },
        },
        render: ({ text }) => <p>{text}</p>,
      },
    },
  }}
  // You export function here
  onPublish={(data) => uploadSomewhere(data)}
/>;

Once that’s in place, you get a fully functional, user-friendly editor right out of the box:

That simplicity, combined with its open-source flexibility, makes Puck a great fit for a variety of projects beyond just page building.

✅ Puck’s strengths

🔹 Pure open-source under an MIT license

Puck is fully open-source under the MIT license, making it a solid choice for both internal tools and commercial applications. There are no restrictive terms or hidden limitations—you can use it or fork it however you see fit. You don’t need to subscribe to anything or work around a specific platform, you embed the editor within your app and do whatever you want with it.

What really sets Puck apart, though, is its strong community-driven development. The project has an active online presence, with real-time support available on Discord, social media, and GitHub. Issues and feature requests don’t just sit unanswered—new ideas from the community are actively reviewed, planned, and implemented in each update. Also, if you contribute, your work is recognized and valued, which makes it great if you enjoy open-source collaboration.

🔹 Free-form drag-and-drop

Puck’s drag-and-drop experience feels intuitive, flexible, and polished. Unlike the other editors on this list, this one provides a clear visual preview of how elements will be reorganized before they’re placed, making layout adjustments smooth and predictable. More importantly, it’s not limited to a rigid block-based structure—you can freely drag elements into any CSS layout, including grids and flexboxes. Because of this Puck is a strong contender for both UI design or simple content authoring. In fact, you could use it for both at the same time for different user roles, since it provides a useful permissions API to disable and enable features on demand.

🔹High flexibility

One of the best things about Puck is that you don’t have to sacrifice developer experience for customization. You can use it with its default UI for a quick setup, extend it as much as you need, or even fully replace it. It gives you the same deep customization that GrapesJS offers, but with the convenience of out-of-the-box behavior like Builder.io, and you can mix and match as much as you want of each side—go fully headless, use Puck’s UI as-is, or integrate just the parts you need.

Also, since Puck is just a React component that lets you drag and drop other components, it works seamlessly with all React.js environments like Next.js or Remix. And because its API is unopinionated, it’s not limited to page building—you can use it as a layout design tool, whether it’s a PDF creator, an infographic designer, or something completely custom. If it’s made of React components, Puck can handle it.

Another major plus is that Puck lets you keep your layouts fully independent from any backend. It exports pages as JSON with a clean, easy-to-migrate schema, meaning you’re never locked into a vendor-specific backend.

🔹 Gentle learning curve - Easy to start building

Unlike GrapesJS, which requires you to build your own UI from scratch, Puck comes with a functional, ready-to-use interface out of the box. This means you can start building immediately and refine your setup over time, rather than needing to fully understand the entire API before getting anything useful done. Because of this, developer onboarding is much smoother—there’s no steep learning curve, and you won’t have to invest time training your team just to get started. Instead, you can focus on actually building and delivering value to your users.

Another big plus is that Puck is unopinionated, so there’s no need to introduce users to vendor-specific concepts or workflows. You can shape the editor to fit their existing knowledge and preferences, reducing friction and making adoption even easier.

🔹 Plugin API

Puck also provides a Plugin API. This means you can build some common custom behavior you may have on multiple editors once, package it, and reuse it as much as you need without repeating or rethinking setups and ensuring you remain consistent across all the experiences you build.

You don’t need to build your own plugins either, Puck already has an active ecosystem of community-built plugins for things like rich text editing, styling libraries, and specific CMS integrations.

❌ Puck’s limitations

🔻 No out-of-the-box storage

Puck is purely a visual editor library, not a full CMS. This means it doesn’t come with built-in storage or backend support—you’ll need to handle that part yourself. While this gives you complete control over how and where your data is stored, it also means that if you’re looking for a fully managed, plug-and-play solution, Puck might not be the best fit. If your project requires a backend and you don’t already have one in place, you’ll need to set up your own storage system or integrate it with an existing CMS or database.

🔻 Still in Pre-1.0 Development

Puck is still in its early stages, with a version number below 1.0. This means that while it’s already a powerful and flexible tool, some APIs are still evolving and could change. The good news is that the team has been clear about their commitment to backward compatibility—they aim to minimize breaking changes and provide ample time for migrations when necessary. Still, if you're looking for absolute long-term stability right now, this is something to keep in mind.

🔻 No collaboration features

Puck doesn’t come with real-time collaboration out of the box. If your project requires multiple users editing the same content simultaneously, you’ll need to set up your own solution—whether that’s using WebSockets, CRDTs, or an existing third-party service. While this gives you the flexibility to implement collaboration in a way that fits your stack, it does mean extra effort on your end if collaborative editing is a core requirement.

🎯 Best For

Puck is a great choice if you want full control over your page builder while keeping development time minimal. It’s ideal if you:

Need a fully embeddable, customizable editor that blends seamlessly into your app’s UI.
Already have (or plan to use) a headless CMS, REST API, or other backend setup—or simply want to keep your options open without vendor lock-in.
Want to keep content editing entirely separate from your backend, ensuring flexibility and future-proofing your architecture.

That said, Puck might not be the best fit if:

You’re looking for a fully managed, plug-and-play solution with built-in backend storage.
You need absolute long-term API stability right now—while stability is improving, some APIs are still evolving as Puck matures.
Real-time collaboration is a must-have and you don’t have the bandwidth to implement it yourself.

If those trade-offs work for you, Puck offers a powerful, open-source alternative to proprietary page builders, with plenty of flexibility to make it truly your own.

Storyblok - Headless CMS

Storyblok is, first and foremost, a headless CMS that happens to include an optional visual editor. It helps developers and content creators manage structured content efficiently while providing an integrable visual editing experience.

At first glance, Storyblok might seem to "break" the headless CMS model by offering an editor. However, rather than functioning like a traditional CMS, it achieves this through SDKs and iframes, allowing developers to integrate a visual editing experience in their client code without being locked into a specific UI. This approach gives the flexibility of a headless CMS while maintaining the core advantages of a traditional one.

That said, because Storyblok is a proprietary CMS first, page builder second, there are inherent trade-offs. Let’s break down its strengths, limitations, and when it makes the most sense to use.

✅ Strengths of Storyblok’s editor

🔹 User-Friendly Visual Editor

Storyblok’s editor allows users to preview and edit content dynamically on different client apps. This works by integrating an SDK into your client code that in turn embeds your app in the editor through an iframe. This means that instead of adding the editor to your app, you’re embedding your app into their editor, which can be useful if you need a quick way to enable visual content creation with a solid out-of-the-box user experience.

🔹 Streamlined component implementation

Storyblok lets you add custom components to the editor as draggable blocks for users. To enable this, the editor’s SDK maps your React components to the content types you’ve defined in Storyblok’s CMS schema. This approach works well for structured content and makes integrating your React applications more seamless. Instead of handling complex configurations, you simply implement the components for each content type you want to support.

🔹 Multi-Framework Compatibility

While this article focuses on React, Storyblok’s editor also works with Vue, Next.js, Astro, Svelte, and more. This means that, if you are working in a project that needs a page builder that works across multiple frameworks—say, different departments in a company using different stacks—Storyblok can be a solid choice for you.

🔹 Collaboration & Workflow Tools

A major advantage of Storyblok is its editorial collaboration features. If you integrate this editor, you can also expect out of the box support for role-based access control, versioning, and approval workflows. This makes it ideal for teams that need a structured content creation and review process.

❌ Limitations of Storyblok’s editor

🔻 Locked into Storyblok’s Ecosystem

Unlike standalone page builders, Storyblok’s editor is only available when using its vendor specific CMS and SDKs. This means your client code is dependent on Storyblok, making it difficult to switch to a different backend or page builder later on. This is what we would call vendor lock-in, which is a risk you should consider before selecting this page builder for your project.

🔻 Proprietary & SaaS

Storyblok operates as a SaaS product, requiring a paid subscription. This means the editor is an external service you use and pay regularly, it’s not yours, and it's not part of your product. You can’t change or fork it, and you’ll only be able to use it as long as you’re able to pay for it. As I mentioned before, you embed your code in their editor, and not the other way around. While that may be useful in the short term, that could be a dealbreaker for you if, in the long run, you plan to migrate lots of pages to some other system.

Also, at larger companies, proprietary tools like Storyblok need to go through a lengthy procurement process, which may not be viable for you or your project restrictions.

🔻 Limited Control Over the Editor

The page builder exists as a separate application hosted by Storyblok, which means:

Users must navigate to a different website to access it, requiring separate credentials from your admin panel and possibly providing a different user experience than your own—making the creation flow feel disconnected.
You can’t embed or modify the editor’s UI or behavior, as it’s a completely separate application. This makes it unsuitable for projects requiring editor customization.

🔻 Steep learning curve

Understanding Storyblok’s content structure (Spaces, Stories, Blocks) can be overwhelming, particularly for those new to headless CMSs. There are a lot of concepts you, and your users, will need to learn in order to start using this CMS and integrating it to your application. This means you will have to invest some additional time in learning, documenting and training of your team and non-technical users.

🎯 Best for

Storyblok is a great fit if you’re looking for a headless CMS with a built-in page builder, especially if structured content management is a top priority in your project and editorial teams need a visual interface.

However, if you need more design features or a self-hosted, standalone, or highly customizable page builder, Storyblok is not the best choice for you.

Builder.io - Headless CMS

Builder.io is a proprietary headless visual CMS designed for low-code and no-code experiences, with a strong emphasis on its visual editor. In fact, Builder.io calls itself a “visual development platform”—a fitting description since it provides a packaged environment for visually building and deploying content-driven webpages.

While it shares similarities with Storyblok, there’s a key distinction: Storyblok is a headless CMS first and a page builder second, whereas Builder.io treats both equally. This makes it a strong choice for projects that need structured content management alongside extensive design features and a packaged backend.

✅ Strengths of Builder.io’s editor

🔹 Advanced visual editing

At first glance, Builder.io’s visual editor looks a lot like Storyblok’s, but after using it, I found it to be more polished—especially when it comes to drag-and-drop functionality. You can actually drag blocks onto the canvas and get a better sense of where they’ll land in the layout, which makes it feel more intuitive for UI design rather than just content authoring.

🔹 Powerful developer tooling

From a developer’s perspective, integrating Builder.io’s editor isn’t all that different from Storyblok. You install an SDK, link your project on Builder.io’s site, register your components, and decide where the content should render—that’s pretty much it. Once set up, users can edit pages directly on Builder.io’s platform.

The improvement on this, though, is that you can visually integrate it into your code using Builder.io’s SDK and DevTools. This reduces the need for manual setup and cuts down on boilerplate, making the process smoother, guided and overall more intuitive.

🔹 Extensive docs

The platform has plenty of documentation to guide both developers and end users, which is always a plus. There are detailed guides, videos, and examples to help with setup, customization, and editor usage, making it easier to get things working without too much guesswork.

That said, if you’re new to CMS platforms, the sheer amount of docs can feel a bit overwhelming. You might find yourself clicking through page after page just to piece things together. It’s thorough, but expect a bit of a learning curve if you’re not familiar with how headless CMSs work.

🔹 Modular approach

Like Storyblok, Builder.io lets you add your own React components to the editor for drag-and-drop use. However, the way it handles this is a bit different—you define your components in your code first, and they become available in the editor after. This setup works well if you're integrating Builder.io into a single project, since you maintain full control over the component definitions on your code. But if you’re managing multiple code bases, it can get tricky to keep track of what needs to be implemented where, since there’s no single source of truth inside the editor itself.

One area where this editor stands out, though, is its support for Symbols and Templates. Symbols let you group and reuse components with specific props across pages directly in the editor, while templates work the same but allow updating those props. This can be handy because you can implement smaller, more flexible components and let users mix and match them however they need.

❌ Limitations of Builder.io’s editor

🔻 It’s a proprietary solution

Builder.io’s biggest limitation is that it’s a proprietary platform—you can’t self-host or embed the editor in your app, as both your designs and the editor run on their servers. You might see mentions of Builder.io being open-source, but to clarify: only their SDKs are, not the visual editor itself. This means you’re limited to the features and customization options they provide. If you want to modify the page building experience, such as introducing your own field types or embedding it into your own application, this could be a deal breaker.

Another thing to keep in mind is content portability. Your pages are tightly integrated with Builder.io’s system, and while they offer an AI-powered export feature, it’s paywalled—so migrating your pages elsewhere could come with extra costs.

🔻 Access under SaaS model

Builder.io also follows a SaaS model requiring a monthly subscription to use their editor. Pricing depends on multiple factors, but a key one is “visual views”—which works similarly to how Google Analytics counts page views. This means that your costs will scale based on how often your pages are viewed, even though Builder.io only hosts your content and page design with your client still needing to be hosted somewhere else.

🔻 Overkill for simple page editing

If all you need is a straightforward visual editor for building pages or layouts, Builder.io is overkill. It’s a powerful platform with a lot of features, but if you’re not planning to use its CMS, code generation, targeting, or integrations, it could feel more complex and expensive than necessary. While it offers plenty of built-in solutions, if you're just looking for flexible drag-and-drop page editing with export functionality that can easily be embedded in your app and integrated with any backend, there are simpler more modular tools that might be a better fit.

🎯 Best for

Builder.io shines in situations where you're working on more complex projects, especially in areas like e-commerce or content-heavy websites where you need a reliable visual editor packaged with a CMS out of the box. If you're already planning on using a content management system (CMS) or know that you'll need one in the future, Builder.io's integration capabilities can be a real asset.

That said, if you don’t need that level of complexity, already have a CMS and want to keep it separate from your page editing, prefer a budget-friendly option, or need to embed the page building into your own application, there are other solutions on this list that might serve you better.

Tiptap - Visual Editor

While Storyblok and Builder.io offer full-page editing experiences with structured CMS capabilities, Tiptap takes a different approach. It’s not a traditional page builder but rather an embeddable headless editor built on ProseMirror. This means that instead of giving you a predefined UI to work with, it provides the underlying logic, leaving you in full control of the interface, interaction and level of functionality you want to provide in your page builder.

Because of this, Tiptap is an interesting option if you want to build a fully custom page editing experience rather than relying on an off-the-shelf solution. While it’s primarily a text editor, it can be extended to support drag-and-drop for custom React components and it allows exporting to HTML and JSON schemas, making it a viable option for page building.

✅ Tiptap’s strengths

🔹 Open-source under an MIT license

One of Tiptap’s biggest strengths is its open-source nature. Licensed under MIT, it gives you full control to modify, commercialize and extend it however you need—no vendor lock-in, no restrictions. You get a powerful, headless editor that you can integrate into your own app and self-host without worrying about licensing fees or usage limits.

🔹 Extension based architecture

Tiptap is built around an extension-based architecture, making it highly customizable while also providing a solid set of pre-built extensions for common editing needs like code blocks, horizontal rules, and more. This means that while Tiptap is headless, you don’t have to start from scratch or reinvent the wheel every time you add essential functionality.

🔹 Open-source backend for collaborative editing

Another positive aspect to Tiptap is that, while it doesn’t tie you to any specific backend, it does provide an optional open-source server to add fullstack self-hosted collaborative editing. This server is based on the Y.js framework, and it provides a lot of the functionality you need to add an scalable collaborative editing experience, without much work from your side. Interally that is the same stack they use as the base of their own cloud SaaS solution, so it’s a nice touch that they’re releasing it to the public so you can decide if hosting it by yourself or not.

🔹 Highly customizable

Since Tiptap is a headless, block-based text-editing framework, you’re free to design the UI and interactions exactly how you want while still benefiting from the structured logic and opinionated API it provides. There’s no default styling and no forced layouts—just a foundation you can build on to fit your needs. This is extremely useful if you have a specific requirements for a page builder, or want to make the editor your own unique experience without any third party branding.

❌ Tiptap’s Limitations

🔻 Requires a long time to set up

Tiptap is powerful, but it’s not something you can just plug in and start using right away. Since it’s completely headless, it doesn’t provide an intuitive drag-and-drop UI out of the box—you have to build that yourself. As I mentioned before, this gives you full control, but it also means setup can take significantly longer compared to traditional page builders. If you're a developer looking for a drop-in solution, you might find the initial work required to be a bit of a hurdle.

🔻 Steep learning curve and not beginner friendly

Another disadvantage to Tiptap being fully headless, is that getting up to speed with it takes time. It’s a framework and it requires you to build your UI from the ground up, so you’ll need to spend time learning its APIs, understanding its extension-based architecture, and figuring out how to structure your editor effectively. If you're working with a team, onboarding will also take longer, as everyone will need to get familiar with Tiptap’s approach.

🔻 Falls short for design-in-browser

Since Tiptap is fundamentally a text editor, its page-building capabilities have limits—especially when it comes to full-fledged layout design. While you can extend it to support drag-and-drop interactions, its architecture is more suited for a block-based editor (similar to Notion) rather than a flexible, multi-column, responsive design tool.

If you need true WYSIWYG page-building with pixel-perfect layout control, getting Tiptap to work that way will require significant effort. You’d have to implement a lot of custom logic to handle grid systems, nested components, and fluid layouts, which is a level of complexity other page builders handle natively.

🎯 Best for

If you have the time and resources to build a custom page builder—especially one focused on text-heavy content like documents, articles, blogs, or knowledge bases—Tiptap could be a great fit. It gives you full control over the editing experience while letting you decouple content storage from it.

However, if you still want Tiptap’s open-source ethos, customization capabilities, and extension/plugin based architecture, but need a more traditional page builder with flexible layout editing and an extensible UI out of the box, you might find other editors on this list better suited.

GrapesJS - Visual Editor

Like Tiptap, GrapesJS is a headless framework, but one specifically built for page editors, giving you the flexibility to create fully custom drag-and-drop experiences without being tied to a specific CMS, backend, or ecosystem. This means it provides the core editing logic but leaves most of the UI implementation and content management entirely up to you.

GrapesJS has two main offerings: the open-source framework which is headless and unopinionated, and the Studio, a cloud-based, proprietary version that adds additional out-of-the-box functionality and an opinionated API to reduce boilerplate when setting up your editor. For this section, I'll focus on the framework version, since it's the one we have full control over.

✅ GrapesJS’s strengths

🔹 BSD 3-clause License

Similarly to Tiptap, one of the biggest advantages of GrapesJS is its open-source nature. The framework is licensed under BSD-3, meaning you’re free to use, modify, and extend it without any licensing fees or restrictions. This also means, your editor won’t be tied to a specific platform or ecosystem and you will be able to embed it in your app and customize it however you see fit.

🔹 Headless editor for page building

GrapesJS is a headless editor specifically built for creating web pages. This means that, unlike Tiptap, which focuses on text editing, it provides a drag-and-drop interface and APIs for handling HTML elements, and CSS. However, like Tiptap, it doesn’t enforce a specific UI, styling system, or backend, giving you full control over the user experience, from the toolbar setup to the styling logic.

The drag-and-drop interaction feels very similar to Builder.io’s and is generally smoother than Storyblok’s. However, it does have some quirks—especially when working with complex multi-column layouts using Grid or Flexbox since it doesn’t always preview how elements will fit before you drop them.

🔹 Exports to HTML and CSS

One of the key features of GrapesJS is its ability to export content as HTML and CSS. Unlike some page builders that rely on proprietary data formats or JSON-based schemas, GrapesJS ensures that whatever you build can be used in any web environment without extra processing. This makes it especially useful for apps that generate static pages or email templates, and makes it play nicely with most web frameworks and CMS platforms, giving you plenty of flexibility in how you integrate it into your system.

❌ GrapesJS’s limitations

🔻 Long setup

GrapesJS gives you a lot of flexibility, but that comes with a tradeoff—setup can be time-consuming. Since it’s a headless framework, it provides only a minimal pre-built UI and page-building experience. That means you’ll need to configure everything yourself, from the layout to the styling system, to get it fully production-ready. And it’s not just about visuals, even basic features, like adding custom fields for a block, require extra work compared to other editors since the framework is designed to be as unopinionated as possible.

🔻 Steep learning curve and complex API

GrapesJS offers a powerful API, but it’s not the most intuitive. Unlike some page builder libraries that use a more declarative, configuration-based approach, GrapesJS requires you to work directly with JavaScript and HTML-based APIs to define building blocks, styles, and interactions. This is mainly because it’s framework-agnostic and there’s no built-in abstraction for popular front-end libraries, which makes it feel a bit barebones at first.

This also means getting up and running will take you some effort—you’ll need to spend time reading the documentation and getting familiar with its way of handling editor logic. This is similar to what happened with Tiptap, it has lot of flexibility, but that comes with a steeper learning curve.

🔻 JS Only – Not a React-based component system

While GrapesJS supports JSX, it doesn’t provide built-in integrations for React. It does provide a React package, but its focus is more on rendering and editing the editor UI rather than allowing you to add React components as draggable elements. Basically this means you can’t directly use React components as building blocks within the editor, which isn’t helpful if you’re using React for your front-end.

🔻 Can be hard to use for non-technical users

Even though GrapesJS is a visual editor, it leans heavily on an HTML and CSS model. So, while you can create custom blocks and fields and abstract away some complexity, the core editing logic you will be writing still revolves around direct manipulation of HTML elements and styles.

This makes the final editor great for developers who want fine-grained control, but it’s not as user-friendly for non-technical users who expect a more guided, WYSIWYG-style experience.

🎯 Best For

GrapesJS is a solid choice if you need a highly customizable, self-hosted page-building framework with full control over the editing experience. It’s especially useful if your project requires an open-source alternative with highly customized drag-and-drop page building.

That said, if you're looking for a more plug-and-play visual editor with built-in CMS features, tools like Builder.io or Storyblok might be a better fit. If your focus is more on text heavy content rather than full-page layouts, Tiptap would be a better match. And if you need an embeddable editor that works out of the box with free-form drag-and-drop, flexible APIs, and open-source licensing, then Puck might be a better fit.

Closing up

In this article I explored some of the most relevant page builders out there, and broke down their strengths, limitations, and ideal use cases. More than just listing features, I tried focusing on flexibility—how these tools balance developer and user experience, and avoiding vendor lock-in—which are key factors when choosing the right editor for your project.

At the end of the day, like everything in engineering, the best tool you can choose will depend on your needs. Whether you're looking for a fully customizable framework, a quick-to-integrate solution, or something in between, I hope this breakdown helped you navigate the options and make your decision. 🚀

💬 If you have more editors in mind you think I should add to the list, thoughts, questions, or just want to chat more about this, feel free to reach out! You can find me on LinkedIn, X, and Bluesky. Looking forward to hearing your take!

Revolutionizing Drag-and-Drop in React: Introducing Puck 0.18

Fede Bonel Tozzi — Thu, 23 Jan 2025 13:29:44 +0000

Puck is the open-source visual editor for React, that you can embed in any application to create the next generation of page builders and no-code products. Give us a star on GitHub! ⭐️

🎉 Puck 0.18 is here! 🎉

This update marks a massive leap forward with the debut of our groundbreaking drag-and-drop engine with support for CSS Grid and Flexbox. This eliminates all previous limitations and introduces unparalleled flexibility, so your users can drag and drop any component, anywhere.

What do I mean by this? See it for yourself:

This means your page builders can now support virtually any design your users dream up—all without writing a single line of code. No more compromises or workarounds—just pure creative freedom.

But this milestone doesn’t just improve Puck—it transforms it into the ultimate design-in-browser tool by adding a level of flexibility that scales to the level of granularity that you need.

Whether you want a straightforward page builder with page-level blocks or a highly granular visual layout builder for smaller, atomic components, Puck can adapt to your needs. From websites to document editors to infographic designers—if it’s built with React components, Puck can now bring it to life.

Let’s take a closer look at the main features in Puck 0.18 and how you can start using them today.

For a deeper dive, check out the official release notes and full changelog.

Updating to the New Version

Before we dive in, let’s get you up to speed. Getting started with the latest version of Puck is quick and straightforward.

If you’re starting fresh with a new project, just install it using your favorite package manager:

npm install @puckeditor/core --save

Or if you are already using Puck you can update it in your existing project by running the following command:

npm update @puckeditor/core

That’s it! Since this update doesn’t introduce any breaking changes, you can dive straight into exploring all the new features without worrying about compatibility issues. 🎉

🏗️ Free-form multidimensional Drag and Drop

The new drag-and-drop engine is a complete game changer for user and developer experience.

Previously, Puck’s drag-and-drop functionality was primarily restricted to the vertical axis, and could be extended with the DropZoneAPI to create multi-column layouts. This, however, could be cumbersome for users, as it required manually positioning components in each column and, if you wanted to increase the number of columns and reflow your items, you had to reorganize them manually:

With the release of 0.18, you can now freely drag and place React components in any direction on the canvas—vertically, horizontally, or within responsive grids. Puck will also give you instant visual feedback, showing exactly how the layout will look once the component is dropped:

"Okay, that sounds amazing, but how do I set this up?" That’s the best part—it’s incredibly simple. All you need to do is style your wrapper DropZone as a grid or flexbox in your Puck config:

  Grid: {
    //... fields configuration
    render: ({ columns }) => (
     <DropZone
       zone="my-grid"
       style={{
         display: "grid",
         gridTemplateColumns: `repeat(${columns}, 1fr)`,
       }}
     />
    ),
  },

That’s it—this turns the DropZone's div into a CSS grid, ensuring that any component you drag and drop inside automatically aligns with the grid's flow. The same approach works seamlessly for flex containers too.

🧱 Advanced CSS layouts

Previously, all Puck components were wrapped in a div. This made it impossible to treat items as a direct descendant of their parent DropZone, which can be necessary when working with CSS grid or flex-based layouts.

Using the new inline parameter, you can remove the Puck wrapper entirely and treat the child as a direct descendant of the DropZone. This is useful for building layouts because rules like flex-grow or grid-column behave exactly how you’d expect.

For example, say you wanted to create a card grid where users can customize how many rows and columns each Card spans by using the grid-column and grid-row CSS rules—all you’d need to do is configure your components like this:

Card: {
  //... fields configuration
  // Enable inline mode to remove default wrapper div
  inline: true,
  render: ({ spanRow, spanCol, puck }) => {
    return (
      <div
        style={{
          border: "1px solid black",
          gridColumn: `span ${spanCol}`,
          gridRow: `span ${spanRow}`,
        }}
        // Pass the drag reference to the new draggable div
        ref={puck.dragRef}
      >
        Card Content
      </div>
    );
  },
},
Grid: {
  //... fields configuration
  render: ({ columns, rows }) => (
    <DropZone
      zone="my-grid"
      style={{
        display: "grid",
        gridTemplateColumns: `repeat(${columns}, 1fr)`,
        gridTemplateRows: `repeat(${rows}, 1fr)`,
      }}
    />
  ),
},

With that, your users can build sophisticated multi-column layouts by simply tweaking a few fields in the editor:

This also works perfectly with flex containers and items. For instance, you could create a flex container that responsively wraps and scales items up and down depending on the viewport size and the item’s flex rule:

This is just the tip of the iceberg. By ditching the wrapper and giving developers direct control over the components, Puck now opens the door for more ambitious layouts, more interactive experiences, and entirely new kinds of projects.

💠 Drag between DropZones containers

One of the most exciting upgrades in this release is the ability to drag components between DropZones containers.

Previously, you could only drag and drop between zones that shared the same parent, which, let’s be honest, felt pretty limiting. If your user needed to move something to another level in the hierarchy, they’d have to copy, paste, or re-enter the data entirely. Now, all that friction is gone. Whether you're moving a component or an entire DropZone between sibling zones, dragging it into a nested child, or even pulling it back up to a parent, it just works—no extra setup required on your end.

This change streamlines the entire experience. Moving components around is now intuitive and seamless. For example, if you’re building a dashboard with nested widgets, you can now rearrange everything in one go—dragging charts, controls, or headers into any level of the layout:

PRO TIP: If you need to keep some restrictions, you can use the allow prop on the DropZone to control which components it accepts.

📏 Dynamic DropZone height

DropZones also received a major quality-of-life update: they now dynamically shrink to match the height of their children and accurately preview the final render.

Even better, you can now configure a placeholder height for empty DropZones. This lets you define how they behave when there’s nothing inside, giving you full control over your editor’s layout and allowing you to visually prioritize DropZones as needed.

To do this, all you need to do is set the minEmptyHeight prop in your DropZone. For example, you might want to show a short navbar DropZone at the top of your canvas while keeping the main content DropZone as tall as possible. In 0.18 you can now do this by configuring your root like this:

root: {
  render: () => (
    <div>
      <DropZone
        zone="nav"
        // Set the height to 80 pixels when nothing is inside
        minEmptyHeight={80}
        style={{ maxHeight: 100 }}
      />
      <DropZone
        zone="main"
        // Set the height to 500 pixels when nothing is inside
        minEmptyHeight={500}
      />
    </div>
  ),
},

This will create a thinner DropZone at the top of the page and a bigger one at the bottom:

By setting minEmptyHeight, you ensure your layouts look consistent while keeping empty zones accessible and user-friendly for your specific use-case.

It’s a small change, but one that makes a huge difference for creating polished page building experiences.

🔠 Extending component Drawers with Grids

By default, Puck renders the Drawer—a container for all your draggable components—as a vertical list in the sidebar. In the past, you could personalize where you wanted this list to live by using custom interfaces. However, if you wanted to display it in a grid, that wasn’t really possible due to our legacy drag-and-drop engine. But with the new engine in 0.18, that limitation is gone.

Explore the rest of 0.18

There’s so much more packed into 0.18 that I couldn’t fit into this post! If you’re into the nitty-gritty, the release notes have all the details. But if you’d rather skip reading through them, here’s a quick rundown of the other features outside the drag-and-drop updates:

Toggle interactive hotkey: Easily toggle component interactivity in Preview mode with the cmd+i (or ctrl+i on Windows) hotkey—super handy for testing interactive components without leaving your editor.
Select parent action: Quickly select a component’s parent directly from the action bar. It’s a small tweak, but it makes navigating nested components a lot smoother.
No more position: fixed: We’ve ditched this style from the default layout to make embedding Puck in your app a whole lot simpler.
New <ActionBar.Label> component: Organize and section off parts of your action bar using the new <ActionBar.Label> component—it’s great for creating more intuitive component selectors.

For those ready to dive deeper, check out the updated documentation to get up to speed.

Closing words

Puck v0.18 really is a testament to what’s possible when we build tools with our community. This update is not just a step forward—it’s a leap forward, and it wouldn't have been possible without your feedback and contributions. Thank you.

We love hearing about what you're building with Puck! Maybe you’re experimenting with drag-and-drop editors in React, crafting pixel-perfect designs, or dreaming up use cases we haven’t even thought of yet. Whatever it is, let us know!

Let’s keep the conversation going:

Share your feedback, check out community plugins, ask questions, or just nerd out with us on Discord
Follow along for updates and insights on Bluesky and X
If you’re enjoying the ride, we’d love your support—give us a 🌟 on GitHub. It means a lot, and it helps us keep building the tools you love.

So here’s to Puck v0.18, the community, and all the things you'll create with it 🥂. Let’s see what you build next!

Managing application state in Puck

Fede Bonel Tozzi — Tue, 14 Jan 2025 13:16:08 +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 has been rapidly growing, and it’s been awesome to watch! 🚀 Developers from all backgrounds are pushing the boundaries of what this open-source visual editor can do. But as more people dive into Puck, one question keeps coming up in our Discord community:

“How can I pass data or share state between components in Puck?”

In other words: how do you make one component react to changes in another? For example, you might create a DropZone component with a search input, so that any lists dropped inside it can read its value:

At first, Puck’s built-in magic might make you think it handles state in a unique way. But here’s the thing: Puck is just React—and so are the components you pass into it. That means that you can rely on any state library or tool you would normally use to manage and share data between components. For this article, I’ll keep it simple and teach you how to solve this problem by using Context.

Before we get started: I’ll assume you’ve got a basic understanding of Puck and how it works. If you’re new here, that’s totally fine—you’re welcome to follow along! But I’d recommend checking out the getting started guide first to get familiar with the basics

Project Setup

To make things easy, I’ve prepared a basic React project on GitHub with Puck pre-installed and ready to go. Clone and install it by running the following commands in your terminal:

git clone https://github.com/FedericoBonel/basic-puck-app
cd ./basic-puck-app
npm install

Already working on an existing project? No problem at all! You can simply install Puck as a dependency with NPM:

npm i @puckeditor/core --save

And if you’re using frameworks like Next.js or Remix, Puck offers official recipes to make the setup process seamless.

For this tutorial, I’ll assume you’ve cloned the GitHub repo to keep things straightforward. That said, the concepts and steps will apply to any setup—just update the file names as needed to fit your project’s structure.

Configuring Puck

With your project ready to go, the next step is to configure Puck. Open the src/App.jsx file and swap its contents with the code below. This will set up Puck with a basic config for dragging and dropping two components:

A Dashboard component that greets users and contains a DropZone for nesting other components
An ArticleList component that displays a list of articles inside the Dashboard

// App.jsx
import { Puck, DropZone } from "@puckeditor/core";
import "@puckeditor/core/puck.css";

// The configs for your draggable components
// Ideally you would pull these out into their own files
const dashboardConfig = {
  render: () => {
    return (
      <div
        style={{
          minWidth: "fit-content",
          maxWidth: "50%",
          margin: "auto",
        }}
      >
        <h3>Welcome User!</h3>
        <DropZone zone="list" />
        <a href="/signup">Sign up now</a>
        <p style={{ fontSize: "14px" }}>
          Already have an account? <a href="/signin">Sign in here</a>
        </p>
      </div>
    );
  },
};

const articleListConfig = {
  render: () => {
    // These articles could come from an external data source
    const articles = ["Puck", "React State", "NextJS"];

    return (
      <ul>
        {articles.map((article, i) => <li key={i}>{article}</li>)}
      </ul>
    );
  },
};

// The Puck configuration object
const config = {
  components: {
    Dashboard: dashboardConfig,
    ArticleList: articleListConfig,
  },
};

// Your editor component
const App = () => {
  return <Puck config={config} data={{}} />;
};

export default App;

Once you’ve updated the file, start the application in development mode, and navigate to http://localhost:5173 to verify everything is working as expected:

npm run dev

Great! Your basic setup is now complete. Next, let’s dive into adding shared state to your editor.

Adding Context

React Context is the perfect solution for our problem because it offers a simple way to share and manage data across all your components—both inside and outside the editor. It creates a "global state" that you can access whenever needed, making it ideal for scenarios where you need to pull in data from outside Puck—like the selected theme or the logged-in user—or share data between Puck components.

In this guide, I’ll walk you through two common use cases for React Context within Puck:

Accessing data stored outside Puck: We’ll begin by setting up a context containing a logged-in user’s data outside of the <Puck /> component, and then access it from within Puck components.
Passing data to a nested component: Next, we’ll set up a search query context within the Dashboard. This will allow us to capture a user’s search query, store it in the context, and pass it down to the ArticleList component. The goal is to filter the list of articles based on the user’s query, demonstrating how to pass data between a parent and child Puck component.

Step 1: Define the Context outside Puck

Setting up context in Puck follows the same pattern as any React app. You create a Context provider to define and manage your shared state, wrap it around a parent component, and access or update the state wherever it's required in your app.

Start by creating a new Context for the user data. This Context will include both the user object and a function to update the user state.

// context/userContext.jsx
import { createContext, useContext, useState } from "react";

// Create the Context
const UserContext = createContext(null);

// Custom hook to use the User Context
const useUserContext = () => {
  const context = useContext(UserContext);
  if (!context) {
    throw new Error("useUserContext must be used within a UserProvider");
  }
  return context;
};

Step 2: Create the Context Provider outside Puck

Next, create a UserProvider component that will wrap your Puck editor. This provider will manage the user state and make it available to all children.

For the sake of brevity, I’m using a dummy user and the setter function returned by useState.

// context/userContext.jsx

//... existing setup

//eslint-disable-next-line react/prop-types
const UserProvider = ({ children }) => {
  // Start the context state with a dummy user
  const [user, setUser] = useState({
    name: "John Doe",
  });

  return (
    <UserContext.Provider value={{ user, setUser }}>
      {children}
    </UserContext.Provider>
  );
};

export { UserProvider, useUserContext };

Step 3: Integrate the Provider with Puck

To integrate the provider with your Puck editor, simply wrap the editor with the UserProvider. You can put the UserProvider anywhere above the editor in your component tree (like in your index file), and it'll work just fine. Once you've done that, all your editor components will have access to the context!

// App.jsx
import { UserProvider, useUserContext } from "./context/UserContext";

//... existing setup

const App = () => {
  return (
    <UserProvider>
      <Puck config={config} data={{}} />
    </UserProvider>
  );
};

Step 4: Consume the Context in the Puck Components

Now you can access the UserContext in any of your Puck components. Following our use case example, let’s update the Dashboard component so that it displays a “welcome back” message for logged-in users and a “generic welcome” message for guests.

// App.jsx
import { useUserContext } from "./context/UserContext";

//... existing setup

const dashboardConfig = {
  render: () => {
    // Access the user context
    const { user, setUser } = useUserContext();

    return (
      <div
        style={{
          minWidth: "fit-content",
          maxWidth: "50%",
          margin: "auto",
        }}
      >
        {/* Read the user's name */}
        <h3>Welcome back {user?.name ?? ""}</h3>
        <DropZone zone="list" />

        {/* Update the user on logout */}
        {user && <button onClick={() => setUser(null)}>Sign out 🏃🚪</button>}
      </div>
    );
  },
};

//... the Puck config

If you're using eslint, you may see the linting error ‘React Hook "useUserContext" is called in function "render" that is neither a React function component nor a custom React Hook function.’ This is because ESLint can’t recognise the syntax of the render function as a component.
To fix this you can pull the render function into its own component and pass it (render: WelcomeCard), or ask ESLint to ignore the line (eslint-disable-next-line react-hooks/rules-of-hooks).

Now you can go back to the editor, drag and drop the new Dashboard component, and you'll see that the UserContext is being accessed to display the “welcome back” message for the dummy logged-in user:

If you were to publish that data and pass it to the Render component using the same config and UserProvider, the result would look just as it was in the editor, and you could also click on the sign-out button to clear the logged-in user state:

With this done, you now have a state originating outside of Puck, seamlessly passed to and updated by Puck components! ✔️

Step 5: Adding a search query

Now let's move to our second use case: Passing data from a Puck component to another.

To make this work, we’ll add a search query input and an initialQuery prop to the Dashboard component. This will allow users to filter the list of articles and give us the option to set an initial query for them to start with.

// App.jsx
import { createContext, useContext, useState, useEffect } from "react";

//.. existing setup

const dashboardConfig = {
  // Set the default props for the initial query field
  defaultProps: {
    initialQuery: "React",
  },

  // Create a field for setting the inital query
  fields: {
    initialQuery: {
      label: "Initial Search Query",
      type: "text",
    },
  },

  // Read the initial query prop
  render: ({ initialQuery }) => {
    // ... existing dashboard setup

    // Create the state for the search query
    const [query, setQuery] = useState(initialQuery);

    // Update the query's value from the editor's field
    useEffect(() => {
      setQuery(initialQuery);
    }, [initialQuery]);

    return (
      <div
        style={{
          minWidth: "fit-content",
          maxWidth: "50%",
          margin: "auto",
        }}
      >
        <h3>Welcome back {user?.name ?? ""}</h3>

        {/* Create the input the user will use to filter the lists */}
        <input
          type="text"
          value={query}
          onChange={(e) => setQuery(e.target.value)}
        />

        <DropZone zone="list" />
        {user && <button onClick={() => setUser(null)}>Sign out 🏃🚪</button>}
      </div>
    );
  },
};

Step 6: Provide context from a Puck component

Next, let’s set up a context in the Dashboard component to pass down the query state. This will ensure that when the user updates the search input, the new query is stored in the context and shared with the ArticleList or any other component dropped inside the Dashboard.

// App.jsx
//... existing setup

// Create the query context that will pass down the query state
const QueryContext = createContext();
const useQueryContext = () => useContext(QueryContext);

const dashboardConfig = {
  render: () => {
    // ... existing dashboard setup

    return (
      <QueryContext.Provider value={{ query, setQuery }}>
        {/* ... existing dashboard component */}
      </QueryContext.Provider>
    );
  },
};

//... the Puck config

Step 7: Consume the Context from Puck components

Now, we’ll read the context in the components that are dropped inside the context provider. In our case, we’ll consume the context in the ArticleList component, which the user has nested inside the Dashboard via the DropZone. This allows the ArticleList to respond to changes in the search query and update accordingly.

// App.jsx
//... existing setup

const articleListConfig = {
  render: () => {
    // Access the query state
    const { query } = useQueryContext();

    // Filter out the articles based on the query
    const articles = ["Puck", "React State", "NextJS"].filter(
      (article) => article.indexOf(query) !== -1
    );

    //... existing return statement
  },
};

If you now head into the editor, drag a Dashboard component onto the canvas, drop an ArticleList inside it, and modify the initialQuery field, you’ll see the list dynamically filter the articles based on the query. 🎯

You could even expand this setup by having multiple list components with different content reuse the same query context.

🎉 And that’s it! You now have shared state between nested Puck components. 🎉

Pros & Cons of using React Context

✅ Pros:

Provides a robust solution for sharing state across components, both inside and outside Puck
Integrates seamlessly with existing React patterns and components
Can handle complex logic and state
Zero external dependencies as React Context comes with React

❌ Cons:

Performance can degrade if you frequently update state at the top of a large component tree, as every subscriber needs to re-render
When managing multiple context providers, things can become harder to debug

Taking it further

There are a bunch of ways in which you can improve managing shared state in Puck depending on the complexity of your editor:

Optimize context usage - If you notice performance issues or unnecessary re-renders, consider splitting your context into smaller, more focused contexts. This allows components to subscribe only to the parts of the state they need, minimizing re-renders.
Incorporate state libraries - If you have multiple shared states and more complex logic, you could move beyond React Context and use your favorite state library. Whether it’s Redux, Zustand, or another library your project is already using, these can simplify managing complex state and improve rendering performance.
Leverage server-side state - If your application relies heavily on data fetched from a server, consider using a library like TanStack Query or SWR. These libraries manage caching, re-fetching, and synchronization for you, reducing the need for complex shared client-side state.

Your Turn to Build Smarter with Puck 💡

Taking shared state management in Puck to the next level unlocks a world of possibilities for building dynamic, reactive page builders. I’m excited to see the unique and powerful apps you’ll build using these strategies.

So, if this article has inspired you to build something, you have a question about Puck or you want to contribute, here’s how you can get involved:

🌟 Star Puck on GitHub to show your support and inspire others to explore.
🤝 Join our Discord community to connect, learn, and collaborate.
📢 Follow us on X and Bluesky for sneak peeks, updates, and tips.
📘 Explore the documentation for advanced techniques to supercharge your builds.

The future of Puck—and no-code innovation—is in your hands. Start building today, and let’s redefine what’s possible together! 🙌

Using CSS variables to create dynamic themes in Puck

Fede Bonel Tozzi — Wed, 08 Jan 2025 13:53:24 +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! ⭐️

When integrating Puck into your page-building product, a common requirement is to allow your users to centrally manage the theme of the page without having to make adjustments to every component.

For example: users need a way to manage font styles globally—even for components already added to the page. Here’s how that could look in action:

Since Puck is just a React component, there are lots of ways to solve this problem (as well as managing other, more complex state). For this article, I’ll focus on one of the simplest yet most powerful approaches—CSS properties. Let’s dive in!

For this tutorial, I’ll assume you have a basic understanding of Puck and its functionality. If you’re new to Puck, don’t worry—you’re still welcome to follow along! However, I recommend checking the getting started guide to familiarize yourself with the fundamentals.

Project Setup using Vite

I’ll start by setting up a project using Vite's scaffolding script. You’re welcome to follow along or skip this section if you already have a project with Puck.

If you’re using Next.js or Remix you could also use one of the official Puck recipes for setting up your project.

Creating Project

To get started, open your terminal and run the following commands to create a new Vite project:

npm create vite@latest puck-global-themes -- --template react
cd puck-global-themes
npm install

Installing Puck

Next, install the Puck package:

npm i @puckeditor/core --save

Deleting conflicting styles

When you start a new project with Vite, it'll come with some default styles that will clash with Puck's. To fix this, delete src/index.css and src/App.css, then remove their imports from src/main.jsx and src/App.jsx:

// main.jsx
import "./index.css"; // Remove this line

// App.jsx
import "./App.css"; // Remove this line

Rendering the Puck editor

With the basic project structure ready, head over to your src/App.jsx file and replace its contents with the code below. This will set up Puck with a basic config for dragging and dropping Heading and Paragraph components:

Note that, for the sake of simplicity I'm using in-line styling in this example

// App.jsx
import { Puck } from "@puckeditor/core";
import "@puckeditor/core/puck.css";

// The configs for each of your draggable components
// Ideally you would pull each of these to their own files

const headingConfig = {
  defaultProps: {
    title: "Title",
  },
  fields: {
    title: {
      type: "text",
    },
  },
  render: ({ title }) => {
    return (
      <div>
        <h1>{title}</h1>
      </div>
    );
  },
};

const paragraphConfig = {
  defaultProps: {
    content: "This is a paragraph...",
  },
  fields: {
    content: {
      type: "textarea",
    },
  },
  render: ({ content }) => {
    return (
      <div>
        <p>{content}</p>
      </div>
    );
  },
};

// The Puck configuration object
const config = {
  components: {
    Heading: headingConfig,
    Paragraph: paragraphConfig,
  },
  root: {
    render: ({ children }) => {
      return (
        <main
          style={{ fontFamily: "Arial, Helvetica, sans-serif", padding: 32 }}
        >
          {children}
        </main>
      );
    },
  },
};

// Your editor component
const App = () => {
  return <Puck config={config} data={{}} />;
};

export default App;

Finally, run the application in development mode, navigate to http://localhost:5173, and check that everything is working as expected:

npm run dev

Awesome! Now that you have a foundation to build on, let's add theming for your users.

Adding theming

As I mentioned before, CSS custom properties are an excellent choice for adding interactive theming to your editor. Why is this a great approach? Because it’s lightweight, doesn’t require external dependencies, and is (for the most part) handled natively by the browser.

Setup

To add dynamic theming with CSS properties you'll need to define your theme variables as properties at some parent of the component that needs them. This could be Puck's root component or any other parent component in your editor's hierarchy, it really doesn't matter as long as you define them and then read them where you need using the var CSS function.

For this tutorial, I'll focus on using Puck's root component so that users are able to set font size and color for headings and paragraphs in a single place at the top level of the editor:

Step 1: Define the Variables

Start by defining an object to centralize all the CSS variables names. This will improve consistency and save you from the rabbit hole of debugging issues caused by mistyped property names in CSS.

Pro tip: If you’re using TypeScript you could use an enum instead of an object to get additional type safety

// App.jsx

// The names for each one of the CSS variables
const SharedCSSVars = {
  fontColor: "--font-color",
  headingFontSize: "--heading-font-size",
  paragraphFontSize: "--paragraph-font-size",
}

Step 2: Add the Variables to the Parent Component

Next, update the root config to include the props and fields for the theme variables. This will allow users to update the custom properties directly from within the root fields of the editor.

To do this, you’ll need to define the fields for the new root props and their default values:

// The Puck configuration object
const config = {
  components: {
    //... existing components
  },
  root: {
    // The default values for your CSS variables
    defaultProps: {
      fontColor: "#000000",
      headingFontSize: 32,
      paragraphFontSize: 24,
    },
    // The fields for your CSS variables
    fields: {
      fontColor: {
        label: "Font color (hex)",
        type: "text",
      },
      headingFontSize: {
        label: "Heading font size (px)",
        type: "number",
      },
      paragraphFontSize: {
        label: "Paragraph font size (px)",
        type: "number",
      },
    },

    //... the root's render function
  },
};

After that, in the root’s render function, read the custom properties from the props and pass them to the root element as CSS variables.

// The Puck configuration object
const config = {
  components: {
    //... existing components
  },
  root: {
    //... the root fields configuration

    render: ({ children, fontColor, headingFontSize, paragraphFontSize}) => {
      return (
        <main
          style={{
            fontFamily: "Arial, Helvetica, sans-serif",
            padding: 32,
            // The new variables using our names object and the new props
            [SharedCSSVars.fontColor]: fontColor,
            [SharedCSSVars.headingFontSize]: `${headingFontSize}px`,
            [SharedCSSVars.paragraphFontSize]: `${paragraphFontSize}px`,
          }}
        >
          {children}
        </main>
      );
    },
  },
};

If you now go to the editor, you should see the new fields at the root level for each one of the props. There is no visual feedback yet, but if you inspect the styles of the editor’s root, you will see the variables being set with every change you make to the fields.

Step 3: Access Shared Variables in Child Components

Finally, access the theme variables in the components you need by using the var CSS function in your styles.

In our example, you’ll add them in the headingConfig and the paragraphConfig:

const headingConfig = {
  //... The heading fields configuration

  render: ({ title }) => {
    return (
      <div>
        <h1
          style={{
              // Here we are reading the shared styles for the headers
            color: `var(${SharedCSSVars.fontColor})`,
            fontSize: `var(${SharedCSSVars.headingFontSize})`,
          }}
        >
          {title}
        </h1>
      </div>
    );
  },
};

const paragraphConfig = {
  //... The paragraph fields configuration

  render: ({ content }) => {
    return (
      <div>
        <p
          style={{
              // Here we are reading the shared styles for the paragraphs
            color: `var(${SharedCSSVars.fontColor})`,
            fontSize: `var(${SharedCSSVars.paragraphFontSize})`,
          }}
        >
          {content}
        </p>
      </div>
    );
  },
};

If you return to the editor, drag and drop some headings and paragraphs, and then modify the fields at the root level, you’ll notice that all the headings and paragraphs update to reflect those changes:

🥳 And that’s it! Your users are now able to define a theme seamlessly applied across different components in their pages.

Pros & Cons of using CSS properties

✅ Pros:

Simple and intuitive setup
Built-in cascading and override functionality in page hierarchy, allowing for easy management of shared styles and the ability to customize individual components
Zero external dependencies and lightweight footprint—CSS custom properties are natively supported by browsers
Less boilerplate and maintenance complexity than other options

❌ Cons:

Only suitable for simple styling—can't handle complex data or logic
Debugging can be difficult when nesting multiple levels of CSS property overrides

Taking it further

Depending on your specific use case, there are plenty of ways to take your editor theming even further:

Use predefined themes - In some applications, you may need to provide default theme options—like Dark, Light, or Minimal. For this, you could use a select field with multiple theme objects. These objects can group all the CSS properties as a unit, allowing users to easily swap between different themes for their pages without having to fill in single fields.
Integrate styling libraries – For larger editors, it may be better to use a styling library to leverage pre-built styles, streamline your definitions, and reduce boilerplate. Libraries like Tailwind or Emotion can easily integrate with Puck, giving you flexibility and efficiency while maintaining a polished look. In fact, Puck even offers an Emotion plugin that simplifies the integration process for you!
Add component-level theme overrides – Sometimes users may need to customize individual components in their pages so that they stand out from the rest of the theme. Since we’re using CSS properties, this can easily be achieved by overriding the parent-level theme variables at the component level. For example, you could add an optional font color field inside your Heading component that, if provided, would redefine the CSS property specifically for that h1 element.

Stay Connected and Keep Building 🚀

I hope this tutorial has empowered you to leverage CSS variables for dynamic theming in Puck-powered page builders. The open-source developer community is at the heart of Puck's evolution, and I can’t wait to see the innovative apps you create!

We’re dedicated to pushing Puck’s capabilities even further, with a constant stream of new features, including a revolutionary drag-and-drop engine for complex grids and layouts launching imminently, and a suite of new plugins on the horizon.

So, if Puck has inspired you or if you’d like to stay up to date with the latest features, here’s how you can get involved:

⭐ Star us on GitHub to support the project and inspire others to explore its potential.
💬 Join our Discord community to share your projects, ask questions, and collaborate.
📢 Follow us on X and Bluesky for the latest updates, sneak peeks, and feature announcements.
📚 Dive deeper into the official documentation for advanced techniques and insights that can take your no-code workflows to the next level.

DEV Community: Fede Bonel Tozzi

Puck 0.21: AI beta, rich text editing & new plugin rail

What's new in Puck 0.21

Puck has moved

AI page generation

Rich text editing

New UI: The Plugin Rail

Add your own plugin UI

New mobile interface

New API: Change slot element with as

New hotkeys: Delete and backspace

New component: Puck.Layout

New field override: custom

Declaration merging for the ComponentConfig type

Declaration merging for the Metadata type

Declaration merging for Field types

Other changes

New interaction: Deselect components on second click

New component: ActionBar.Separator

New Puck prop: height

New Puck prop: _experimentalFullScreenCanvas

New default viewport: Full-width

Make viewports fill the container

New ActionBar.Action prop: disabled

New Puck API function: resolveDataById

New Puck API function: resolveDataBySelector

New Puck API function: getParentById

Access parent data in resolvePermissions

Access parent data in resolveData

Access metadata in resolveFields

New trigger for resolveData: move

Use CSS units in Slot minEmptyHeight prop

Disable cache in external fields

Use functions for defaultItemProps in array fields

Use JSX for getItemSummary in array fields

Use JSX for getItemSummary in external fields

How to upgrade

Full changelog

Contributors

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

What Makes Puck Different

Step 1: Add Puck

Installing Puck

Running Puck

Adding Typescript to Puck

Adding Components to Puck

Step 2: Integrate Tailwind

Installing Tailwind

Migrating to Tailwind

Applying Tailwind Dynamically

Option 1: Predefined static classes and inline styling (simplest)

Option 2: Predefined dynamic classes (longer boilerplate)

Bonus Option: Import all classes by using the CDN (Heaviest)

Wrapping up

Integrating a Page Builder with Contentful

Table of Contents

📝 1. Set up Contentful

👩‍💻 2. Add Puck

Installing Puck

Running Puck

🔗 3. Connect Puck with Contentful

Reusing Components

📰 4. Edit and Publish your Pages

Taking your Page Builder Further

🔚 Wrapping up

Top 5 Drag-and-Drop Libraries for React in 2025

TL;DR

🏗 Picking the right drag-and-drop library

dnd-kit

✅ dnd-kit’s strengths

❌ dnd-kit’s limitations

🎯 Best for

hello-pangea/dnd

✅ hello-pangea/dnd’s strengths

❌ hello-pangea/dnd’s limitations

🎯 Best for

pragmatic-drag-and-drop

✅ pragmatic-drag-and-drop’s strengths

❌ pragmatic-drag-and-drop’s limitations

🎯 Best for

New API: Change slot element with `as`

New component: `Puck.Layout`

New field override: `custom`

Declaration merging for the `ComponentConfig` type

Declaration merging for the `Metadata` type

New component: `ActionBar.Separator`

New `Puck` prop: `height`

New `Puck` prop: `_experimentalFullScreenCanvas`

New `ActionBar.Action` prop: `disabled`

New Puck API function: `resolveDataById`

New Puck API function: `resolveDataBySelector`

New Puck API function: `getParentById`

Access `parent` data in `resolvePermissions`

Access `parent` data in `resolveData`

Access `metadata` in `resolveFields`

New trigger for `resolveData`: `move`

Use CSS units in Slot `minEmptyHeight` prop

Disable cache in `external` fields

Use functions for `defaultItemProps` in array fields

Use JSX for `getItemSummary` in array fields

Use JSX for `getItemSummary` in external fields

Give hints with `collisionAxis`