payload-plugin-visual-editor

v1.0.0

Published

17 hours ago

Inline visual editing for Payload CMS live preview (text fields)

0High
0Medium
0Low

krzysztofradomski

payload-plugin-visual-editor

Inline visual editing for Payload CMS live preview.

Edit text directly in the preview iframe. Changes sync back to the admin document form and save as a draft when you click Done.

Features

Edit text, textarea, number, and richText fields from the live preview
Automatic text matching — no data-* attributes or field wrappers in your frontend
Case-insensitive matching (e.g. CSS text-transform: uppercase on titles)
Edit / Done control in the admin document bar when live preview is active
Commits in-progress edits and saves a draft when you click Done
Per-collection allowlists and blocklists for field paths

Requirements

Payload ^3.84.0
@payloadcms/ui and @payloadcms/live-preview (peer dependencies)
Live preview configured on the collection
VisualEditorListener mounted in the frontend layout used for preview URLs

Installation

pnpm add payload-plugin-visual-editor

Setup

1. Register the plugin

import { payloadVisualEditor } from 'payload-plugin-visual-editor'

export default buildConfig({
  plugins: [
    payloadVisualEditor({
      collections: {
        // Enable all editable field types for this collection
        articles: true,

        // Or restrict which fields can be edited in the preview
        'static-pages': {
          excludeFields: ['slug'],
        },

        // Allowlist only specific paths
        pages: {
          fields: ['title', 'hero.body'],
        },
      },

      // Optional — defaults to text, textarea, number, richText
      editableFieldTypes: ['text', 'textarea', 'number', 'richText'],
    }),
  ],
})

The plugin registers the Edit / Done admin control automatically. You do not need to wire admin components manually.

After adding the plugin, regenerate your project's import map so Payload can resolve the admin UI:

payload generate:importmap

2. Enable live preview on a collection

export const Articles: CollectionConfig = {
  slug: 'articles',
  admin: {
    livePreview: {
      url: ({ data }) => `/articles/${data?.slug}?payloadLivePreview=true`,
    },
  },
  fields: [
    { name: 'title', type: 'text', required: true },
    { name: 'slug', type: 'text', required: true },
    { name: 'content', type: 'richText' },
  ],
}

Preview URLs must be served by the same frontend layout where you mount VisualEditorListener.

3. Mount the frontend listener

Add the listener once to the root layout of your live-preview frontend (not the admin layout):

import { VisualEditorListener } from 'payload-plugin-visual-editor/client'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        <VisualEditorListener />
      </body>
    </html>
  )
}

Collection options

| Value | Description | | ------------------------------ | ----------------------------------------------------- | | true | All fields matching editableFieldTypes are editable | | { fields?: string[] } | Only these dot-paths (e.g. meta.title) | | { excludeFields?: string[] } | Remove paths from the editable set (e.g. slug) |

Usage

Open a document that has live preview enabled.
Click Edit in the admin bar (next to save / draft controls).
In the preview, hover text that matches a configured field — it is outlined in blue.
Click to edit inline, then blur to apply the change to the form.
Click Done to exit edit mode, commit any active edit, and save the document as a draft.

Edits update the admin form immediately. Draft saves are debounced while editing; Done flushes any pending save.

Live preview pages with React state

If your preview page subscribes to @payloadcms/live-preview and stores document data in React state, pause updates while the user is editing. Otherwise incoming preview events will re-render the page, wipe contenteditable state, and lose the cursor.

Use the hooks exported from the client entry:

'use client'

import { subscribe, unsubscribe } from '@payloadcms/live-preview'
import { useVisualEditorEditMode, useVisualEditorMode } from 'payload-plugin-visual-editor/client'
import { useEffect, useRef, useState } from 'react'

export function ArticlePreview({ initialArticle, serverURL }) {
  const isLivePreview = useVisualEditorMode()
  const isVisualEditing = useVisualEditorEditMode()
  const [article, setArticle] = useState(initialArticle)
  const pendingRef = useRef<typeof initialArticle | null>(null)
  const editingRef = useRef(isVisualEditing)
  editingRef.current = isVisualEditing

  useEffect(() => {
    if (!isLivePreview) return

    const listener = subscribe({
      callback: (data) => {
        if (editingRef.current) {
          pendingRef.current = data
          return
        }
        setArticle(data)
      },
      initialData: initialArticle,
      serverURL,
    })

    return () => unsubscribe(listener)
  }, [initialArticle, isLivePreview, serverURL])

  useEffect(() => {
    if (!isVisualEditing && pendingRef.current) {
      setArticle(pendingRef.current)
      pendingRef.current = null
    }
  }, [isVisualEditing])

  return (
    <article>
      <h1>{article.title}</h1>
      {/* render other fields */}
    </article>
  )
}

See dev/components/PostPreview.tsx in this repo for a full working example.

How matching works

The listener loads editable field paths from the plugin API, subscribes to live-preview document data, and builds a lookup from field values (including rich text plain text and paragraph segments). Visible DOM text is matched case-insensitively.

Your templates only need to render the same text as stored in Payload — no special markup. Text that does not appear in the DOM (hidden fields, computed-only values) cannot be edited visually.

API

`GET /api/visual-editor/fields?collection={slug}`

Returns editable field descriptors for an enabled collection.

{
  "collection": "articles",
  "fields": [
    { "path": "title", "type": "text" },
    { "path": "richContent", "type": "richText" }
  ]
}

Returns 400 if the collection is not enabled for visual editing.

Exports

| Import | Description | | ------------------------------------- | ----------------------------------------------------------------------------- | | payload-plugin-visual-editor | Plugin (payloadVisualEditor) and types | | payload-plugin-visual-editor/client | VisualEditorListener, hooks, VisualEditorAdmin (registered by the plugin) | | payload-plugin-visual-editor/rsc | Re-exports for RSC-compatible setups |

Troubleshooting

| Issue | What to check | | ------------------------------- | ----------------------------------------------------------------------------------------------- | | Edit button missing | Collection enabled in payloadVisualEditor({ collections }) and live preview configured | | No blue outlines in preview | VisualEditorListener mounted in the preview frontend layout; field text is visible in the DOM | | Edits lost while typing | Preview page re-renders on live-preview updates — use the pause/flush pattern above | | Admin build error after install | Run payload generate:importmap in your project |

Contributing

This repository is also a Payload plugin template. For local development, testing, and release workflow, see development.sketch.md.

Local development setup

The plugin's source lives in src/, but the dev app in dev/ (and Payload's auto-generated dev/app/(payload)/admin/importMap.js) imports it under its published name — payload-plugin-visual-editor/client and payload-plugin-visual-editor/rsc — so the dev environment mirrors what consumers see in their own projects.

Because the plugin is not actually installed in node_modules during local development, those subpath imports are wired up through two small pieces of glue (instead of a link:. self-dependency in package.json, which would pollute the published manifest):

dev/tsconfig.json — compilerOptions.paths maps payload-plugin-visual-editor, …/client, and …/rsc to the matching files under ../src/. This is what TypeScript and editors use for type checking and go-to-definition.
dev/next.config.mjs — turbopack.resolveAlias and webpack.resolve.alias map the /client and /rsc subpaths to the same source files at runtime, so both pnpm dev --turbo and the standard webpack build resolve them without a real package install.

dev/payload.config.ts is loaded by the Payload CLI (Node, not Next), so it imports payloadVisualEditor via a plain relative path (../src/index.js) — Node never sees the package name.

If you add a new public entry point under src/exports/, update both the tsconfig paths and the alias map in dev/next.config.mjs to keep the dev app resolving it.

License

MIT

Note

This is open source work for self hosted Payload CMS instances. This plugin has no relation to the official Payload CMS enterprise visual editor.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

payload-plugin-visual-editor

Features

Requirements

Installation

Setup

1. Register the plugin

2. Enable live preview on a collection

3. Mount the frontend listener

Collection options

Usage

Live preview pages with React state

How matching works

API

GET /api/visual-editor/fields?collection={slug}

Exports

Troubleshooting

Contributing

Local development setup

License

Note

`GET /api/visual-editor/fields?collection={slug}`