DEV Community: Puck

Building a plugin for a React visual editor with Puck

Astrodevil — Thu, 12 Mar 2026 16:38:54 +0000

Page builders and visual editors have become central to modern product development. Frontend engineers, product teams, and content operations groups rely on them to build landing pages, dashboards, documentation systems, and internal tools quickly and consistently.

As adoption grows, expectations grow with it. Editors must support customization, structured content, automation, and domain-specific workflows without increasing development and maintenance overhead.

The market reflects this demand. The global low-code development platform market is projected to reach $167 billion by 2030. Organizations continue to invest in visual development systems that enable faster iteration and broader collaboration. As these systems expand in scope and adoption, the architectural responsibility placed on editor frameworks also increases.

Growth introduces complexity. Every feature added directly to the core increases surface area and long-term maintenance costs. As teams introduce metadata panels, validation rules, workflow controls, and UI extensions, the editor becomes tightly coupled and difficult to evolve without clear extension boundaries.

Plugin systems create those boundaries. They define controlled integration points, isolate functionality, and protect the editor’s foundation.

In this article, we examine how to design plugin systems for visual editors and build a working example using Puck.

What Is a Plugin System: Architecture Deep Dive

A plugin system defines a controlled way to extend software without modifying its core. It exposes extension points through a stable contract and allows external modules to register new behavior, UI, or logic.

The core remains responsible for orchestration, lifecycle management, and state ownership. Plugins operate within boundaries defined by that core.

At an architectural level, a plugin system introduces three primary layers:

Core Engine: Owns state, rendering, persistence, and lifecycle management.
Extension API (Plugin Contract): Defines how plugins register, what hooks they can access, and what capabilities they receive.
Plugin Modules: Independent units that implement features through the exposed contract.

This separation enforces control. The core decides when a plugin runs, where it renders, and what data it can access. The plugin does not directly mutate internal systems. It communicates through defined interfaces.

Key Architectural Properties

A well-designed plugin system should provide:

Isolation: Plugins cannot corrupt the global state.
Deterministic Lifecycle: Mount, update, and unmount phases are predictable.
Explicit Extension Points: UI slots, event hooks, and state access are intentional.
Encapsulation: Editor state and internal systems remain protected behind defined APIs.
Composable Registration: Multiple plugins can coexist without conflict.

This architecture scales by allowing new capabilities to be introduced without changing the foundation. Features can be enabled or removed independently, while the core remains lean, stable, and protected.

When to Use Plugins vs Core Features

Extensible editors require deciding which capabilities belong in the core and which should be implemented as plugins. Core features define the editor’s fundamental architecture, such as rendering, state management, and persistence. Plugins extend the editor through defined extension points without modifying that foundation.

The distinction becomes clearer when viewed side by side.

How Puck Implements the Plugin Contract

Puck is a React-based page builder that lets users create pages by dragging and dropping their own components. Developers register these components through configuration objects, and the editor uses them to build and render pages. Puck is fully customizable and extensible, providing APIs to extend editor behavior or package additional functionality as plugins.

Plugin integration in Puck is straightforward. Plugins can register sidebar panels, add controls, and respond to editor events through clear extension surfaces. They interact with the editor state through documented APIs without reaching into internal systems or modifying rendering logic directly.

The plugin contract in Puck focuses on three responsibilities:

Registration: A plugin declares its identity and attaches to the editor during initialization.
UI Injection: The plugin connects to defined surfaces such as sidebars or inspector regions.
Lifecycle Participation: Plugins can hook into editor behavior such as loading, saving, or validation.

Once registered, the plugin runs as part of your core editor integration. This keeps the editor implementation stable while allowing additional functionality to be added through independent plugins.

Building an Author Info Plugin using Puck

We will build a simple Author Info plugin that demonstrates plugin registration, UI injection, and lifecycle participation inside Puck. The plugin will:

Add a panel to the left sidebar
Capture author name, role, and avatar
Store this data alongside the page state
Validate the metadata before publishing

1. Create a New Puck App

Start by generating a new app using the official Puck starter:

npx create-puck-app author-info-plugin

Choose the Next.js option when prompted. After the setup completes, navigate to the project directory and run the application in development mode:

cd author-info-plugin
npm install
npm run dev

Open your browser at:

http://localhost:3000/edit

You should see the Puck editor interface for the homepage.

2. Understand the Plugin API

Puck plugins can extend the editor interface through the Plugin Rail on the left. Plugins may render UI in this rail, but they can also extend editor behavior through overrides and other integrations.

A plugin object looks like this:

const myPlugin = {
  name: "my-plugin",
  label: "My Plugin",
  icon: <Icon />,
  render: () => <div>My UI</div>,
};

Plugins are wired into the editor by passing them to the plugins prop of the <Puck /> component.

3. Create Your Plugin File

Inside your project, create a file at:

app/puck/plugins/AuthorInfoPlugin.tsx

You can create it with:

mkdir -p app/puck/plugins
touch app/puck/plugins/AuthorInfoPlugin.tsx

Since this example uses icons from lucide-react, install it first:

npm install lucide-react

Then open the file you created and add:

"use client";

import { createUsePuck, Plugin } from "@puckeditor/core";
import { User } from "lucide-react";

const usePuck = createUsePuck();

export const AuthorInfoPlugin: Plugin = {
  name: "author-info",
  label: "Author Info",
  icon: <User />,
  render: () => {
    const data = usePuck((state) => state.appState.data);
    const dispatch = usePuck((state) => state.dispatch);

    const author = data.root?.props?.author ?? {
      name: "",
      role: "",
      avatar: "",
    };

    const updateAuthor = (field: string, value: string) => {
      dispatch({
        type: "replaceRoot",
        root: {
          ...data.root,
          props: {
            ...data.root?.props,
            author: {
              ...author,
              [field]: value,
            },
          },
        },
      });
    };

    return (
      <div style={{ padding: 16 }}>
        <h3>Author Info</h3>
        <input
          placeholder="Author Name"
          value={author.name}
          onChange={(e) => updateAuthor("name", e.target.value)}
        />
        <input
          placeholder="Author Role"
          value={author.role}
          onChange={(e) => updateAuthor("role", e.target.value)}
        />
        <input
          placeholder="Avatar URL"
          value={author.avatar}
          onChange={(e) => updateAuthor("avatar", e.target.value)}
        />
      </div>
    );
  },
};

This plugin renders a component that:

Reads the current page data via usePuck
Updates author metadata via Puck’s dispatcher

This demonstrates how plugins can integrate with the editor state.

4. Register the Plugin

Open the route where the editor is rendered:

app/puck/[...puckPath]/client.tsx

Find the <Puck /> component and update the plugins prop:

import { AuthorInfoPlugin } from "../plugins/AuthorInfoPlugin";

<Puck
  config={config}
  data={data}
  onPublish={async (data) => {
    await fetch("/api/pages", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ data, path }),
    });
    return data;
  }}
  plugins={[AuthorInfoPlugin]}
/>

Now your plugin will appear in the Plugin Rail.

5. Test the Plugin UI

Reload the editor at:

http://localhost:3000/edit

In the left Plugin Rail:

Click Author Info
Enter a name, role, and avatar URL in the fields
Click Publish

Because of your onPublish Implementation: the data will be sent to /api/pages and saved to database.json.

6. Confirm Persistence

After publishing, open:

database.json

You should see:

{
  "/": {
    "root": {
      "props": {
        "author": {
          "name":"Your Author",
          "role":"Writer",
          "avatar":"https://example.com/avatar.png"
        }
      }
    },
    "content": [],
    "zones": {}
  }
}

This confirms the author data was correctly persisted.

Note: In the starter project, this data is saved to a local file, but in a real application, it could be stored in any backend, such as a database or API service.

7. (Optional) Render Author Info on the Frontend

To display author metadata on the frontend, update the page that renders your content. For example, open:

app/[...puckPath]/client.tsx

Add the following below the <Render /> component:

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

{data.root.props.author && (
  <div style={{ padding: 24 }}>
    <h3>Author</h3>
    <p><strong>{data.root.props.author.name}</strong></p>
    <p>{data.root.props.author.role}</p>
    {data.root.props.author.avatar && (
      <img src={data.root.props.author.avatar} width={80} alt="Avatar" />
    )}
  </div>
)}

You can also place that in the root configuration to display the saved metadata on published pages.

That’s it. You now have a fully working Author Info plugin that integrates with the editor state, renders a sidebar panel in the Plugin Rail, and persists metadata through the publishing flow.

Closing

Plugin systems give visual editors a structured path for growth. With clear contracts and defined extension points, teams can introduce new capabilities without reshaping the underlying architecture. This keeps responsibilities separated, reduces risk, and allows the platform to adapt as product requirements expand.

The Author Info plugin we built using Puck shows how an extension can be registered independently, integrate with the editor state, and persist structured metadata. The core remains stable while the plugin delivers focused functionality, demonstrating how modular design supports scalable and maintainable editor systems.

For deeper implementation details, refer to the official documentation: https://puckeditor.com/docs

AI Slop vs Constrained UI: Why Most Generative Interfaces Fail

Astrodevil — Tue, 24 Feb 2026 11:52:06 +0000

TL;DR

AI can generate structured interface layouts and assemble component hierarchies from natural language prompts. When generation is unconstrained, the output diverges from design systems, lacks determinism, and requires downstream refactoring before deployment. Production-grade generative UI requires predefined component registries, validated schemas, and explicit architectural constraints, which is the model implemented by Puck and its constrained generation layer, Puck AI.

Introduction

AI systems can now generate complete interface layouts from natural language prompts. Tasks that previously required manual section planning, component selection, and layout composition can now start from a single instruction.

Yet when these generated interfaces are evaluated against real production standards, limitations become clear. Outputs often conflict with established design systems, introduce structural inconsistencies, and produce layouts that require refactoring before integration.

What appears efficient at the prompt layer frequently shifts complexity downstream into engineering workflows. This gap between demo output and deployable software has led to growing skepticism around generative UI, sometimes informally labeled as “AI slop” to describe output that appears complete but fails architectural validation.

In this article, we will examine where AI meaningfully supports interface generation, where it breaks down in production environments, and why constrained, schema-driven systems are essential for making generative UI operational at scale.

What AI Is Actually Good At in UI Workflows

Before evaluating the limitations of generative UI, it is important to isolate where it provides measurable value. AI is effective at accelerating early-stage interface assembly, particularly when the objective is to convert high-level intent into an initial layout draft.

Consider a product team building a new SaaS landing page. A prompt such as “Create a landing page for an AI analytics platform with a hero section, feature highlights, pricing tiers, and customer testimonials” can reliably produce a logically organized page structure within seconds. The output may not be production-ready, but it establishes a usable structural baseline.

AI performs well in the following areas:

Translating Intent into Layout Structure: AI can map abstract, well-known requirements into recognizable interface patterns. For example, it understands that a landing page typically includes a hero, feature highlights, social proof, and a call to action. This reduces the cognitive load of structuring the page from scratch.
Generating First-Pass Scaffolding: AI can assemble a preliminary hierarchy of sections and placeholder content. This enables teams to visualize information architecture quickly before investing time in refinement.
Automating Repetitive Component Assembly: When working with predefined components, AI can configure repeated structures such as feature cards, pricing tiers, or testimonial blocks with consistent prop patterns. This is particularly useful in systems with modular design libraries.
Supporting Rapid Experimentation: AI allows teams to generate multiple layout variations in minutes, enabling faster exploration of structural alternatives without manual reconfiguration.

AI is therefore effective at structural acceleration, particularly in early-stage development where system rules, design boundaries, and composition patterns are still being defined.

In established product environments, however, structural acceleration must operate within existing architectural constraints to remain viable.

Where Unbounded UI Generation Breaks Down

Many unbounded generation tools produce raw code that must be reviewed, integrated, and redeployed before it can be used in production. Even when the output appears complete, it is not directly executable within an existing system. This shifts responsibility to engineering teams and introduces friction into workflows that are intended to be self-service.

For non-technical users such as marketers or content authors, this model is impractical. Page updates require developer involvement, slowing content publishing and limiting autonomy. Instead of enabling cross-functional workflows, generative UI becomes a developer-only tool.

Below are a few additional architectural limitations to consider:

Design System Violations: Unbounded generation does not inherently respect spacing scales, typography tokens, or component composition rules. It may introduce arbitrary margins, inconsistent heading hierarchies, or layout patterns that are not part of the approved system. Even if visually acceptable, these deviations fragment the design language and undermine maintainability.
Inconsistent Component Usage: In systems with established component libraries, specific components are intended for specific contexts. Free-form generation may misuse primitives, duplicate existing abstractions, or bypass higher-level components entirely. This creates parallel patterns that increase technical debt and weaken reuse.
Non-Deterministic Outputs: Identical prompts can yield structurally different layouts across executions. In production environments, this lack of determinism complicates testing, review processes, and content governance. Predictability is a requirement for scalable systems.
Brand and Compliance Drift: Without embedded context, models default to generic language and layout conventions. They lack awareness of regulatory constraints, accessibility standards, and brand-specific positioning. This introduces risk in industries where messaging and structure must adhere to policy.
Output Requiring Engineering Cleanup: Generated code or markup frequently requires normalization before integration. Engineers must refactor styles, align components with existing abstractions, and correct structural inconsistencies. The perceived acceleration at generation time is offset by downstream rework.

Free-form UI generation, therefore, conflicts with production architecture. Systems designed for reliability, reuse, and governance require structured constraints, not unconstrained synthesis.

The Missing Layer: Constraints

In this context, constraints define what can be generated, how it can be configured, how components can be composed, and how the result is represented at runtime. In real systems, those constraints are implemented through concrete mechanisms like component registry boundaries, schema validation, composition rules, and structured runtime output.

Component registry boundaries limit generation to approved React components. Instead of synthesizing arbitrary markup, the model assembles interfaces from predefined primitives such as Hero, FeatureGrid, or PricingTable. Prop schema enforcement validates inputs against typed definitions, ensuring that required fields, enumerations, and data shapes conform to system expectations. For example, a pricing component may require a structured array of tiers with defined attributes rather than free-form content.

Layout rules and composition limits restrict how components can be nested, preventing structurally invalid trees. Business context injection embeds brand, regulatory, or domain constraints directly into the generation process. Deterministic output structures, typically expressed as structured JSON, ensure predictable rendering and traceable state transitions across environments.

How Puck AI Implements Architectural Constraints

With Puck and Puck AI, the constraints we discussed above are implemented and enforced at the system level rather than inferred at prompt time.

Puck AI is a generative UI layer built on top of Puck’s React visual editor that enables page generation within predefined architectural boundaries.

It operates by assembling interfaces exclusively from registered React components instead of generating code. When a user requests something like “a landing page for an AI analytics platform,” the system composes that page from the components already configured in the application. The result is a deterministic component tree interpreted by Puck at runtime, keeping everything aligned with the existing design system and application logic.

In this workflow, generation is an orchestration process over defined primitives. The AI behavior is shaped by the editor configuration and the components supplied by the development team.

Your browser does not support the video tag.

Puck AI Characteristics

Puck AI demonstrates bounded generation through the following characteristics:

Generation from Registered React Components: The AI selects and composes only those components explicitly registered in the Puck configuration. If the system exposes Hero, FeatureGrid, and PricingTable, those are the only structural primitives available. No new layout elements are introduced outside the approved library.
Structured Page Schema Output: The result of the generation is a structured page definition that maps component types to their configured props and hierarchical placement. This schema is interpreted by Puck at runtime to render the interface. The AI does not directly control rendering logic.
Business Context and Brand Rules: Configuration layers allow teams to define tone, domain context, and structural expectations. These parameters influence how sections are assembled and how content fields are populated, ensuring alignment with product positioning and organizational standards.
Design System Preservation: Because rendering occurs through predefined components, spacing, typography, and layout behavior remain governed by the existing design system. Visual consistency is enforced by the component implementation, not by prompt phrasing.
Deterministic Behavior via Configuration: Through controlled configuration of available components, fields, and generation parameters, teams can narrow variability in output. The same structural intent produces predictable component trees aligned with system rules.

Decision Framework: When AI Should and Shouldn’t Generate UI

Final Verdict

Generative UI is effective when it operates within defined architectural boundaries and established component systems. When generation bypasses those constraints, inconsistency and downstream rework become unavoidable. Production-grade outcomes require schema enforcement, controlled composition, and system-level governance.

To see this model in practice, explore Puck for structured visual editing and try Puck AI for constrained page generation workflows. Puck AI is currently available in beta for teams evaluating controlled generative UI in production environments.

Top AI Libraries for React Developers in 2026

Astrodevil — Mon, 09 Feb 2026 14:00:48 +0000

TL;DR

AI libraries used in React apps serve different purposes. Some run directly in the browser, while others work through backend or API-based workflows.
Many AI tools focus on specific problems like UI integration, data retrieval, or structured content generation, not just chat interfaces or code generation.
Choosing the right AI library comes down to understanding where AI fits into your React app and what role it needs to play.

In this article, let us explore 8 key AI libraries and tools React developers use in 2026, grouped by how they fit into real-world React workflows.

Understanding Where AI Fits in a React Application

AI tools for React are not all designed to solve the same problem. Some run directly in the browser, others live in backend services, and some operate at the UI layer. Understanding where an AI library fits in your application helps you choose tools that work well with React instead of fighting against it.

Client-side machine learning: These libraries run directly in the browser and handle tasks like image recognition or simple predictions. They reduce server dependency and can improve privacy, but they are limited by device performance and browser resources.
LLM and AI backends: These tools handle large language models, agents, and data-heavy workflows. They usually run on the server and are accessed from React through APIs. This layer is best suited for reasoning, retrieval, and complex AI logic.
UI and content generation: Some AI tools focus on generating or assisting with user-facing content and interfaces. These tools work closely with React components and state, making them useful for editors, design systems, and structured UI workflows.

Why AI Tooling Works Better in React Today

Edge runtimes make it easier to run AI logic closer to users with lower latency.
Streaming UI allows React apps to display AI responses progressively instead of waiting for full results.
Full-stack React frameworks simplify connecting frontend components with backend AI services.

Top 8 AI Libraries for React Developers

Below are the top 8 AI libraries for React developers in 2026:

1. Puck AI

Puck AI lets you create an AI page builder for non-technical end users to generate landing pages from a predefined set of components. It produces predictable, production-ready pages instead of raw or ad hoc code.

Deterministic UI generation: Generates pages that conform to existing React component definitions instead of producing free-form code or markup.
Configuration-driven behavior: AI output is constrained by schemas, rules, business context, and tools, allowing teams to control not only what the model can generate, but also what data it can access and which actions it is allowed to perform when generating UI.
Component-native integration: Puck AI uses your existing React components as the building blocks for AI output, enabling AI-assisted page creation that results in real, renderable UI rather than design mockups or intermediate formats.
Editor and CMS workflows: Designed for visual editors, page builders, and structured content systems rather than conversational interfaces.
Low-friction AI adoption: Makes it possible to experiment with AI-assisted UI generation and content creation without setting up full agent architectures, custom prompt pipelines, or model lifecycle management.

2. Tensorflow.js

TensorFlow.js allows machine learning models to run directly inside the browser using JavaScript. It enables React applications to perform inference, and in some cases training, without sending data to a backend server.

Browser-based model execution: Runs ML models using WebGL, WebGPU, or CPU backends, allowing inference to happen entirely on the client side.
Common ML tasks: Supports use cases such as image recognition, object classification, basic predictive modeling, and simple neural networks.
Privacy-preserving inference: Since data does not need to leave the user’s device, it is well-suited for applications with strict privacy or compliance requirements.
Low-latency interactions: Eliminates network round-trip times for inference, enabling faster responses for real-time features like camera-based recognition.
JavaScript-first integration: Works naturally with React and other frontend frameworks without requiring Python-based tooling.

3. ML5.js

ML5.js is a high-level JavaScript library built on top of TensorFlow.js that makes machine learning more accessible in the browser. It abstracts away low-level model handling and provides simple APIs for common ML tasks.

Built on TensorFlow.js: Uses TensorFlow.js under the hood while hiding most of the complexity involved in loading and running models.
Simplified APIs: Provides easy-to-use functions for common machine learning tasks without requiring deep knowledge of neural networks or model architecture.
Pretrained model support: Includes ready-to-use models for vision, text, and audio tasks, allowing developers to get results quickly.
Browser-first design: Runs entirely in the browser and integrates smoothly with React and other frontend frameworks.
Fast experimentation: Well-suited for trying ideas quickly without setting up backend infrastructure or ML pipelines.

5. LlamaIndex.js

LlamaIndex.js is a framework focused on connecting large language models to custom data sources. It provides the tooling needed to ingest, index, and retrieve application-specific data so that AI systems can generate responses grounded in real information.

Data ingestion and indexing: LlamaIndex allows developers to load structured and unstructured data from files, databases, APIs, and document stores into searchable indexes.
Retrieval-Augmented Generation (RAG): Instead of relying only on a model’s training data, LlamaIndex retrieves relevant context from indexed sources and injects it into prompts at query time.
Flexible data connectors: Supports a variety of data formats and storage backends, making it suitable for real-world application data.
LLM-agnostic design: Works with multiple language model providers and can be combined with different inference backends.
Backend-oriented integration: Typically runs on servers or API layers, with React applications consuming results via endpoints.

6. Vercel AI SDK

The Vercel AI SDK is designed to help React developers build AI-powered user interfaces with streaming responses. It focuses on the frontend experience, making it easier to display partial AI output as it is generated rather than waiting for a complete response.

Streaming responses: Supports token-by-token or chunked streaming from language models, allowing AI output to appear progressively in the UI.
React and Next.js integration: Provides hooks and utilities that work naturally with React components and Next.js app and server components.
Model-agnostic design: Works with multiple AI providers, allowing developers to switch models without changing UI logic.
Built-in state handling: Manages loading, streaming, and completion states so developers do not need to implement custom streaming logic.
Edge and server compatibility: Designed to work with serverless and edge runtimes commonly used in modern React deployments.

7. OpenAI JavaScript SDK

The OpenAI JavaScript SDK provides direct programmatic access to OpenAI’s language and generative models from JavaScript and TypeScript environments. It serves as a low-level interface for applications that want full control over how models are used and integrated.

Direct model access: Enables applications to call language, image, and other generative models through well-defined APIs without additional abstraction layers.
No enforced architecture: The SDK does not impose opinions on UI, workflows, or application structure, leaving design decisions entirely to the developer.
Flexible deployment options: Commonly used in server environments, edge functions, or API routes that React applications communicate with.
Fine-grained control: Developers manage prompts, inputs, outputs, error handling, and retries directly, allowing precise control over model behavior.
Composable with other tools: Often used as a foundation beneath higher-level frameworks such as LangChain, LlamaIndex, or custom orchestration logic.

8. Brain.js

Brain.js is a lightweight JavaScript library for building and running neural networks in browser and Node.js environments. It focuses on simplicity and ease of use rather than large-scale or complex machine learning workflows.

Simple neural network support: Provides straightforward APIs for training and running basic neural networks such as feedforward and recurrent models.
JavaScript-first design: Written entirely in JavaScript, making it easy to integrate into React applications or Node.js services without additional tooling.
Browser and server compatibility: Can run in the browser for client-side inference or on the server for lightweight backend predictions.
Low setup overhead: Requires minimal configuration, making it suitable for quick experiments and small-scale ML tasks.
Focused scope: Designed for simple predictive problems rather than deep learning or large language models.

Note: Brain.js has not seen an active release in recent years. While it remains usable for simple tasks and learning purposes, it may not be suitable for systems that require long-term maintenance or rapid ecosystem evolution.

What React Developers Should Pay Attention To

Performance: Whether AI runs in the browser or through APIs directly affects speed and resource usage.
User experience: Streaming responses and responsive UI updates matter more than raw model capability.
Predictability and control: AI output is structured and constrained so it aligns with application state, design systems, and business rules rather than producing free-form or hard-to-integrate results.
Integration with existing components: The best AI tools work with your current React components instead of replacing them.

If you are building visual editors, page builders, or structured content systems in React, Puck AI offers a unique approach to AI-assisted UI that prioritizes predictability, structure, and integration over free-form generation.

Building a Rich Text Editor in React

Astrodevil — Thu, 29 Jan 2026 20:03:13 +0000

Rich text editing is a common requirement in modern React applications, but rarely simple to implement. Allowing users to format text with headings, lists, and emphasis introduces challenges around state, content consistency, and maintainability.

Many applications rely on raw HTML strings or direct use of contenteditable. While this can work at first, it often leads to unpredictable behavior as the application grows. Content becomes harder to validate and version, and easy to break when multiple users or automated systems are involved.

A more reliable approach is to treat rich text as structured data instead of markup. Explicit content models give applications control over content creation, rendering, and extensibility, while aligning naturally with React’s declarative, state-driven model.
In this article, we will explore why rich text editing is hard in React, how structured content helps address these challenges, and how extension-based editors enable safe customization. We will also walk through a step-by-step example using Puck’s rich text editor to demonstrate these concepts in practice.

Why Rich Text Is Hard in React

Rich text editing conflicts with several core principles of how React applications are designed. Many traditional solutions rely on browser-level APIs rather than explicit React state, which makes them harder to control as complexity increases.

Many implementations depend on contentEditable and browser-managed HTML mutations. These operate outside React’s state model and make editor behavior difficult to reason about.
Rendering user-generated HTML without an explicit content model limits an application’s ability to validate, transform, or reason about content reliably over time, which in turn makes it difficult to diff, version, or audit, especially in collaborative or frequently edited environments.
Small markup changes can easily break layouts or violate design and accessibility rules without providing any clear signal to the application.
Raw HTML alone does not convey intent, which makes it unsafe for automated transformations, programmatic editing, or AI-driven workflows without an additional layer of structure and control.

In practice, many editors expose HTML as an interface while managing structured state internally. The core challenge is not the presence of HTML itself, but whether applications retain control and intent over how that HTML is produced and evolved.

Why Use Puck for Rich Text Editing

Puck is an open source visual editor for React that lets teams build custom page builders using their own components. The core of Puck is simply a React editor and a renderer, making it easy to integrate into any React application and define editing behavior through configuration.

Schema-driven fields: Rich text in Puck is defined through explicit field schemas, making the allowed structure and behavior clear and enforceable at the application level.
Built on TipTap: Puck’s rich text editor is powered by TipTap, a widely adopted editor engine known for its extensible and state-driven architecture.
Customizable: Formatting options, heading levels, and editor capabilities can be enabled or disabled.
Extensible by design: New formatting features and behaviors can be added using extensions, without modifying or forking the editor core.
Natural fit for React: Puck’s configuration model aligns with React’s component-driven approach, making rich text editing easier to reason about and maintain.

Step-by-Step Tutorial: Rich Text Editing with Puck

A complete working demo is available in this GitHub repository. You are encouraged to clone the repository and run the project locally to explore the full implementation, or follow the instructions below to set it up from scratch.

To run the demo locally, use the following commands:

git clone https://github.com/Studio1HQ/puck_demo_richtext.git
cd puck_demo_richtext
npm install
npm run dev

Then navigate to http://localhost:3000/edit and experiment with the rich text editor.

1. Setting Up Puck

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

npm install @puckeditor/core

Alternatively, you can scaffold a new project using the official recipe. This sets up a working React and Next.js application with the editor and rendering pipeline already configured.

npx create-puck-app rich-text-demo
cd rich-text-demo
npm run dev

Once the development server is running, navigate to http://localhost:3000/edit to edit a page and http://localhost:3000 to view it.

The Next.js Puck recipe includes the following:

Editor: A visual editor interface where content blocks can be added, configured, and edited.
Renderer: A rendering layer that takes saved editor data and outputs a live page using the same component configuration.
Configuration-driven setup: All editor behavior, available blocks, and field types are defined through a single configuration file, rather than custom editor logic.

For this article, we focus only on the editor configuration and how rich text behavior is defined. Routing, persistence, and deployment details are intentionally kept minimal to keep attention on the core concepts.

2. Adding a Rich Text Editor to Puck

Rich text editing in Puck is defined declaratively through configuration. Instead of manually wiring an editor, handling DOM updates, or managing selection state, rich text behavior is enabled by adding a dedicated field type to a component definition.

To set it up, replace the contents of /puck.config.tsx with the following Puck configuration object.

import type { Config } from "@puckeditor/core";

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

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

    // Basic rich text editor block
    RichTextBlock: {
      label: "Rich Text",
      fields: {
        content: {
          type: "richtext",
        },
      },
      render: ({ content }) => (
        <div style={{ padding: 64, maxWidth: 700, margin: "0 auto" }}>
          {content}
        </div>
      ),
    },
  },
};

export default config;

This file serves as the baseline for all upcoming sections, where we incrementally add control and extensibility.

To enable inline editing in Puck, the [contentEditable](https://puckeditor.com/docs/api-reference/fields/richtext#contenteditable) option is added to the rich text field definition.

Add the following line to the content field of the RichTextBlock in puck.config.tsx:

RichTextBlock: {
  fields: {
    content: {
      type: "richtext",
      contentEditable: true,
    },
  },
  render: ({ content }) => (
    <div style={{ padding: 64, maxWidth: 700, margin: "0 auto" }}>
      {content}
    </div>
  ),
},

Inline editing works well for simple content updates, quick adjustments, and editorial workflows where users benefit from editing content in its final visual context.

3. Customizing Editor Behavior (Control)

Rich text editors are often expected to give users complete freedom, but in most real applications, this leads to inconsistent content and broken design systems. Teams usually need to restrict formatting options to ensure visual consistency, accessibility, and predictable rendering across the application.

Puck lets you selectively enable or disable formatting options based on the needs of the product or team.

Disabling a Formatting Option (Bold Example)

The example below shows how to disable the bold formatting option in a rich text field.

Add the following [options](https://puckeditor.com/docs/api-reference/fields/richtext#options) configuration to the content field of the RichTextBlock in puck.config.tsx:

RichTextBlock: {
  fields: {
    content: {
      type: "richtext",
      options: {
        bold: false,
      },
    },
  },
  render: ({ content }) => (
    <div style={{ padding: 64, maxWidth: 700, margin: "0 auto" }}>
      {content}
    </div>
  ),
},

This configuration removes the bold formatting capability from the editor.

Restricting Heading Levels (Structure)

In rich text editing, allowing unrestricted heading levels often leads to inconsistent content hierarchy and poor accessibility. Most applications only need a small, well-defined set of heading levels to maintain clarity and visual consistency.

Puck also lets you constrain heading behavior through configuration, ensuring that content follows a predictable structure.

The example below restricts headings to H1 and H2 only.

Add the following heading configuration to the options object of the content field in puck.config.tsx:

RichTextBlock: {
  fields: {
    content: {
      type: "richtext",
      options: {
        heading: {
          levels: [1, 2],
        },
      },
    },
  },
  render: ({ content }) => (
    <div style={{ padding: 64, maxWidth: 700, margin: "0 auto" }}>
      {content}
    </div>
  ),
},

Once this is applied, the editor will only allow users to select H1 and H2. All other heading levels are removed from the editor interface and cannot be applied through shortcuts.

Customizing the Menu Bar (UI Control)

Default editor toolbars are designed to cover a wide range of use cases, but in real applications, they often expose more options than necessary. This can overwhelm users and lead to inconsistent content. Most teams benefit from presenting a simplified toolbar that reflects only the formatting options they want to support.

Puck lets you customize the rich text menu bar and decide which controls and components to render, making it possible to control the editor user experience without modifying the editor engine or writing custom UI code.

The example below shows how to define a custom menu bar that exposes only selected controls.

Add the renderMenu function to the content field of the RichTextBlock in puck.config.tsx:

import { RichTextMenu } from "@puckeditor/core";

content: {
  type: "richtext",
  renderMenu: () => (
    <RichTextMenu>
      <RichTextMenu.Group>
        <RichTextMenu.Bold />
      </RichTextMenu.Group>
    </RichTextMenu>
  ),
},

This configuration replaces the default toolbar with a minimal menu that includes only the bold control. All other formatting options are hidden from the interface.

4. Adding Custom Extensions (Extensibility)

Modern rich text editors are not monolithic systems. Instead of baking every feature into the core editor, advanced functionality is added by extending the editor engine itself. This approach keeps the editor lightweight while allowing applications to introduce new capabilities only when needed.

Puck’s rich text editor follows this model. It is built on TipTap, which allows new formatting behaviors to be added by registering extensions through configuration.

The example below adds support for superscript formatting by registering the Superscript extension.

First, install the Superscript extension:

npm install @tiptap/extension-superscript

Then, add the extension to the rich text field configuration in puck.config.tsx:

import Superscript from "@tiptap/extension-superscript";

content: {
  type: "richtext",
  tiptap: {
    extensions: [Superscript],
  },
},

This configuration enables superscript functionality at the editor engine level. The editor now understands superscript formatting and can apply it internally, but users do not yet see a toolbar button or control to trigger it.

Separating editor capability from editor UI is a key design principle. By adding functionality through extensions first, applications can control when and how features are exposed to users. This makes the editor easier to evolve, safer to customize, and better aligned with product requirements.

In the next step, this capability will be surfaced through a custom toolbar control.

Exposing the Extension via a Custom Control

To make the feature usable, the editor needs to expose this capability through the user interface.

This is done by connecting the editor state to the toolbar using a selector and rendering a custom control that responds to that state.

A selector allows the editor to expose information about its current state, such as whether a formatting option is active or whether it can be applied at a given cursor position. This state is then consumed by the menu bar to control button behavior.

The example below shows how to expose the Superscript extension through a custom toolbar button.

Update the content field in puck.config.tsx as follows:

    // Rich text block demonstrating structure, control, extensibility
    RichTextBlock: {
      label: "Rich Text",
      fields: {
        content: {
          type: "richtext",

          // Add custom TipTap extension
          tiptap: {
            extensions: [Superscript],
            selector: ({ editor }) => ({
              isSuperscript: editor?.isActive("superscript"),
              canSuperscript: editor
                ?.can()
                .chain()
                .toggleSuperscript()
                .run(),
            }),
          },

          // Custom toolbar with a Superscript control
          renderMenu: ({ children, editor, editorState }) => (
            <RichTextMenu>
              {children}

              <RichTextMenu.Group>
                <RichTextMenu.Control
                  title="Superscript"
                  icon={<SuperscriptIcon size={16} />}
                  onClick={() =>
                    editor?.chain().focus().toggleSuperscript().run()
                  }
                  active={editorState?.isSuperscript}
                  disabled={!editorState?.canSuperscript}
                />
              </RichTextMenu.Group>
            </RichTextMenu>
          ),
        },
      },
      render: ({ content }) => (
        <div style={{ padding: 64, maxWidth: 700, margin: "0 auto" }}>
          {content}
        </div>
      ),
    },
  },
};

export default config;

This configuration connects the Superscript extension to the editor interface. The selector exposes whether superscript is active and whether it can be applied, and the custom control uses that state to render an interactive toolbar button.

Further Exploration

You can extend this demo by:

Adding more TipTap extensions
Introducing additional editor constraints
Experimenting with different toolbar layouts
Integrating persistence or collaboration features

Key Takeaways

Rich text editing works best when it is treated as a structured system rather than a free form input. By modeling content intentionally, enforcing clear rules, and extending behavior through configuration, teams can build editors that scale reliably with their applications.

Puck fits naturally into this model by combining a structured, rich text engine with a configuration-driven approach that aligns well with modern React development.

Structure over uncontrolled markup: Rich text should encode intent and hierarchy through explicit structure, not rely solely on browser-managed HTML.
Control over free-form editing: Editors should enforce design and content rules instead of relying on manual cleanup.
Extensibility through configuration: New capabilities can be added safely without modifying core editor logic.
Separation of concerns: Editing behavior, user interface, and rendering remain clearly decoupled.

Explore the full demo repository to see these concepts in action, experiment with editor constraints, and extend the rich text editor to fit your own use cases.

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

Puck 0.19: Slots API & performance gains

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

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

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

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

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

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

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

What's new in Puck 0.19

Slots API

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

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

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

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

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

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

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

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

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

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

New function: `walkTree`

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

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

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

Selectors for `usePuck`

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

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

const usePuck = createUsePuck();

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

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

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

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

New hook: `useGetPuck()`

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

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

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

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

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

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

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

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

Metadata API

This was a contribution made by: @jsjexpert

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

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

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

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

Metadata can also be accessed within resolveData:

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

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

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

New recipe: `react-router`

This was a contribution made by: @matthewlynch

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

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

$ npx create-puck-app my-app

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

Other changes

Improved performance

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

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

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

These were the results:

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

Getters for item selectors

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

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

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

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

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

Trigger event in resolveData

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

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

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

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

Custom label icons for fields

This was a contribution made by: @DamianKocjan

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

import { TextCursor } from "lucide-react";

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

Field placeholders

This was a contribution made by: @DamianKocjan

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

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

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

Step size for number fields

This was a contribution made by: @shannonhochkins

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

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

Hiding fields

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

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

New `RootConfig` type

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

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

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

New `replaceRoot` action

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

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

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

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

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

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

How to upgrade

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

Full changelog

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

Contributors

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! 🚀

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!

Puck 0.18: New drag-and-drop engine

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

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

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

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

TLDR

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

Highlights

New drag-and-drop engine

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

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

Fluid layouts

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

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

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

Remove wrapping elements

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

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

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

Dragging between nested DropZones

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

Dynamic DropZone height

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

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

The `<ActionBar.Label>` component

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

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

Parent selector

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

Toggle interactive hotkey

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

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

No more `position:fixed`

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

Breaking changes

Drawer `direction` no longer has any effect

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

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

DropZones are consistently wrapped in a div

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

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

Before

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

After

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

Deprecations

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

Full changelog

Features

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

Bug Fixes

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

Contributors

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

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

Like Puck? Give us a ⭐️ on GitHub.

DEV Community: Puck

Building a plugin for a React visual editor with Puck

What Is a Plugin System: Architecture Deep Dive

Key Architectural Properties

When to Use Plugins vs Core Features

How Puck Implements the Plugin Contract

Building an Author Info Plugin using Puck

1. Create a New Puck App

2. Understand the Plugin API

3. Create Your Plugin File

4. Register the Plugin

5. Test the Plugin UI

6. Confirm Persistence

7. (Optional) Render Author Info on the Frontend

Closing

AI Slop vs Constrained UI: Why Most Generative Interfaces Fail

TL;DR

Introduction

What AI Is Actually Good At in UI Workflows

Where Unbounded UI Generation Breaks Down

The Missing Layer: Constraints

How Puck AI Implements Architectural Constraints

Puck AI Characteristics

Decision Framework: When AI Should and Shouldn’t Generate UI

Final Verdict

Top AI Libraries for React Developers in 2026

TL;DR

Understanding Where AI Fits in a React Application

Why AI Tooling Works Better in React Today

Top 8 AI Libraries for React Developers

1. Puck AI

2. Tensorflow.js

3. ML5.js

5. LlamaIndex.js

6. Vercel AI SDK

7. OpenAI JavaScript SDK

8. Brain.js

What React Developers Should Pay Attention To

Building a Rich Text Editor in React

Why Rich Text Is Hard in React

Why Use Puck for Rich Text Editing

Step-by-Step Tutorial: Rich Text Editing with Puck

1. Setting Up Puck

2. Adding a Rich Text Editor to Puck

3. Customizing Editor Behavior (Control)

4. Adding Custom Extensions (Extensibility)

Exposing the Extension via a Custom Control

Further Exploration

Key Takeaways

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

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

New function: `walkTree`

Selectors for `usePuck`

New hook: `useGetPuck()`

New recipe: `react-router`

New `RootConfig` type

New `replaceRoot` action