Puck Visual Editor

Puck is a modular, open-source visual editor for React.js designed to build custom drag-and-drop experiences using your own application and React components.

Key characteristics:

• React-based: As a React component, it is compatible with all React environments, including Next.js.
• Data Ownership: You own your data with no vendor lock-in.
• MIT Licensed: Suitable for both internal tools and commercial applications.

Puck provides three primary core components for different integration needs:

• <Puck />: The main component used to render the full Puck editor.
• <Render />: Used to render a Data object for a specific Config. This is typically used in your application's frontend to display the content created in the editor.
• <DropZone />: Used to define droppable regions (zones) inside your own custom components, enabling nested component structures within the editor.

Puck is a visual editor for React composed of three main parts:

1. Config: Registers the components and editable fields available to users.
2. The Editor (<Puck>): The UI component used to build pages. It accepts a config, initial data (JSON), and provides an onPublish callback to save changes.
3. The Renderer (<Render>): The component used to display the published pages to end-users. It requires the same config and the page data used during editing.

// 1. Config
const config = {
  components: {
    HeadingBlock: {
      fields: {
        title: { type: "text" },
      },
      render: ({ title }) => <h1>{title}</h1>,
    },
  },
};

// 2. The Editor
<Puck
  config={config}
  data={data}
  onPublish={(data) => {
    // Save data to your database
  }}
/>

// 3. The Renderer
<Render
  config={config}
  data={data}
/>

Any components that are not explicitly assigned to a category will automatically be grouped into a special other category. This category is visible by default. You can customize its appearance (such as its title) using the same configuration options available to standard categories.

const config = {
  categories: {
    typography: {
      components: ["HeadingBlock", "ParagraphBlock"],
    },
    other: {
      title: "Other components",
    },
  },
  // ...
};

Puck provides the FieldTransforms API to modify how field props are rendered within the editor. This is useful for implementing custom rendering behavior, such as wrapping text in specific HTML elements or enabling inline editing.

Important: Field transforms only apply to components rendered within the <Puck> editor component. They are not applied when using the <Render> component.

const fieldTransforms = {
  text: ({ value }) => <div>Value: {value}</div>, // Wrap all text field props in divs
};

const Example = () => <Puck fieldTransforms={fieldTransforms} />;

The collisionAxis prop configures which axis Puck uses for overlap collision detection.

Options:

• x: Detect collisions based on x-axis overlap.
• y: Detect collisions based on y-axis overlap.
• dynamic: Automatically choose an axis based on the direction of travel.

Default behavior based on parent CSS layout:

• grid: dynamic
• flex (row): x
• inline / inline-block: x
• Everything else: y

const config = {
  components: {
    Example: {
      render: () => {
        return (
          <div>
            <DropZone zone="my-content" collisionAxis="dynamic" />
          </div>
        );
      },
    },
  },
};

The migrate function automatically moves any properties that were previously stored directly on the root object into a new props object within root.

Example Transformation:

Before:

{
  "root": {
    "title": "Hello, world"
  }
}

After:

{
  "root": {
    "props": { "title": "Hello, world" }
  }
}