@orion-studios/payload-visual-builder

Visual drag-and-drop page editor for Payload CMS with inline editing, undo/redo, and real-time preview.

Installation

npm install @orion-studios/payload-visual-builder

Features

• Drag-and-Drop Interface: Reorder blocks with smooth animations
• Inline Editing: Edit text directly on the page
• Undo/Redo: 120-item history stack
• Real-time Preview: See changes instantly
• PostMessage Communication: Secure iframe-based architecture
• Save Draft/Publish: Direct integration with Payload's draft system
• TypeScript Support: Full type definitions

Usage

Step 1: Add Visual Builder View to Collection

// src/collections/Pages.ts
import { CollectionConfig } from 'payload'
import { getVisualBuilderView } from '@orion-studios/payload-visual-builder'

export const Pages: CollectionConfig = {
  slug: 'pages',
  admin: {
    components: {
      views: {
        edit: {
          visual: getVisualBuilderView(), // Adds "Visual Builder" tab
        },
      },
    },
  },
  fields: [
    {
      name: 'layout',
      type: 'blocks',
      blocks: [...], // Your blocks from payload-blocks
    },
  ],
}

Step 2: Create Builder Route

// src/app/(frontend)/builder/[id]/page.tsx
import { createBuilderRoute } from '@orion-studios/payload-visual-builder'
import { getPayloadClient } from '@/lib/payload'

export default async function BuilderPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const payload = await getPayloadClient()

  return createBuilderRoute(payload, id)
}

Step 3: That's It!

Open any page in Payload admin and click the "Visual Builder" tab to start editing visually.

Customization

Custom Path and Label

import { getVisualBuilderView } from '@orion-studios/payload-visual-builder'

export const Pages: CollectionConfig = {
  admin: {
    components: {
      views: {
        edit: {
          visual: getVisualBuilderView({
            path: '/editor',
            label: 'Page Editor',
          }),
        },
      },
    },
  },
}

Custom Collection

// Builder route for custom collection
return createBuilderRoute(payload, id, {
  collection: 'posts',
  depth: 2,
})

How It Works

1. Iframe Architecture: The visual builder loads your page in an iframe for isolation
2. PostMessage API: Parent and child communicate via secure postMessage
3. State Management: Changes are tracked locally with undo/redo support
4. Save Integration: Saves directly to Payload's API (draft or published)

Components

BuilderPageEditor

The main visual editor component (exported but typically used via createBuilderRoute).

PageVisualEditorView

Server component wrapper for the admin view.

PageVisualEditorClient

Client component that manages iframe communication and toolbar.

Requirements

• Payload CMS 3.x
• Next.js 14+ or 15+
• React 18+

License

MIT © Orion Studios